diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a1d406ff92de..a901a12043d9 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -79,6 +79,7 @@ doc_classes/* @godotengine/documentation /modules/minimp3/ @godotengine/audio /modules/ogg/ @godotengine/audio /modules/opus/ @godotengine/audio +/modules/qoa/ @godotengine/audio /modules/theora/ @godotengine/audio /modules/vorbis/ @godotengine/audio /modules/webm/ @godotengine/audio diff --git a/COPYRIGHT.txt b/COPYRIGHT.txt index 7f4a3b4b9db4..8badddd5d8ad 100644 --- a/COPYRIGHT.txt +++ b/COPYRIGHT.txt @@ -412,6 +412,11 @@ Comment: PolyPartition / Triangulator Copyright: 2011-2021, Ivan Fratric and contributors License: Expat +Files: ./thirdparty/misc/qoa.h +Comment: Quite OK Audio Format +Copyright: 2023, Dominic Szablewski +License: Expat + Files: ./thirdparty/misc/r128.c ./thirdparty/misc/r128.h Comment: r128 library diff --git a/doc/classes/ResourceImporterWAV.xml b/doc/classes/ResourceImporterWAV.xml index 5336c98d0fca..4f9aab7607da 100644 --- a/doc/classes/ResourceImporterWAV.xml +++ b/doc/classes/ResourceImporterWAV.xml @@ -4,7 +4,8 @@ Imports a WAV audio file for playback. - WAV is an uncompressed format, which can provide higher quality compared to Ogg Vorbis and MP3. It also has the lowest CPU cost to decode. This means high numbers of WAV sounds can be played at the same time, even on low-end deviceS. + WAV is an uncompressed format, which can provide higher quality compared to Ogg Vorbis and MP3. It also has the lowest CPU cost to decode. This means high numbers of WAV sounds can be played at the same time, even on low-end devices. + If you wish to save space while sacrificing a bit of quality, consider importing as QOA instead. $DOCS_URL/tutorials/assets_pipeline/importing_audio_samples.html diff --git a/editor/icons/AudioStreamQOA.svg b/editor/icons/AudioStreamQOA.svg new file mode 100644 index 000000000000..bb06b905e074 --- /dev/null +++ b/editor/icons/AudioStreamQOA.svg @@ -0,0 +1 @@ + diff --git a/editor/plugins/audio_stream_editor_plugin.cpp b/editor/plugins/audio_stream_editor_plugin.cpp index 9b3f24c6255b..b1b8b18aea57 100644 --- a/editor/plugins/audio_stream_editor_plugin.cpp +++ b/editor/plugins/audio_stream_editor_plugin.cpp @@ -36,6 +36,10 @@ #include "editor/themes/editor_scale.h" #include "scene/resources/audio_stream_wav.h" +#include "modules/modules_enabled.gen.h" +#ifdef MODULE_QOA_ENABLED +#include "modules/qoa/audio_stream_qoa.h" +#endif // AudioStreamEditor void AudioStreamEditor::_notification(int p_what) { @@ -266,7 +270,11 @@ AudioStreamEditor::AudioStreamEditor() { // EditorInspectorPluginAudioStream bool EditorInspectorPluginAudioStream::can_handle(Object *p_object) { +#ifdef MODULE_QOA_ENABLED + return Object::cast_to(p_object) != nullptr || Object::cast_to(p_object) != nullptr; +#else return Object::cast_to(p_object) != nullptr; +#endif } void EditorInspectorPluginAudioStream::parse_begin(Object *p_object) { diff --git a/modules/minimp3/doc_classes/ResourceImporterMP3.xml b/modules/minimp3/doc_classes/ResourceImporterMP3.xml index 72868623c76b..e3f88b831302 100644 --- a/modules/minimp3/doc_classes/ResourceImporterMP3.xml +++ b/modules/minimp3/doc_classes/ResourceImporterMP3.xml @@ -6,7 +6,7 @@ MP3 is a lossy audio format, with worse audio quality compared to [ResourceImporterOggVorbis] at a given bitrate. In most cases, it's recommended to use Ogg Vorbis over MP3. However, if you're using an MP3 sound source with no higher quality source available, then it's recommended to use the MP3 file directly to avoid double lossy compression. - MP3 requires more CPU to decode than [ResourceImporterWAV]. If you need to play a lot of simultaneous sounds, it's recommended to use WAV for those sounds instead, especially if targeting low-end devices. + MP3 requires more CPU to decode than [ResourceImporterWAV] and [ResourceImporterQOA]. If you need to play a lot of simultaneous sounds, it's recommended to use WAV or QOA for those sounds instead, especially if targeting low-end devices. $DOCS_URL/tutorials/assets_pipeline/importing_audio_samples.html diff --git a/modules/qoa/SCsub b/modules/qoa/SCsub new file mode 100644 index 000000000000..871cc63f12e9 --- /dev/null +++ b/modules/qoa/SCsub @@ -0,0 +1,9 @@ +#!/usr/bin/env python + +Import("env") +Import("env_modules") + +env_qoa = env_modules.Clone() + +# Godot source files +env_qoa.add_source_files(env.modules_sources, "*.cpp") diff --git a/modules/qoa/audio_stream_qoa.cpp b/modules/qoa/audio_stream_qoa.cpp new file mode 100644 index 000000000000..8dfca689dce2 --- /dev/null +++ b/modules/qoa/audio_stream_qoa.cpp @@ -0,0 +1,298 @@ +/**************************************************************************/ +/* audio_stream_qoa.cpp */ +/**************************************************************************/ +/* This file is part of: */ +/* GODOT ENGINE */ +/* https://godotengine.org */ +/**************************************************************************/ +/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */ +/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */ +/* */ +/* Permission is hereby granted, free of charge, to any person obtaining */ +/* a copy of this software and associated documentation files (the */ +/* "Software"), to deal in the Software without restriction, including */ +/* without limitation the rights to use, copy, modify, merge, publish, */ +/* distribute, sublicense, and/or sell copies of the Software, and to */ +/* permit persons to whom the Software is furnished to do so, subject to */ +/* the following conditions: */ +/* */ +/* The above copyright notice and this permission notice shall be */ +/* included in all copies or substantial portions of the Software. */ +/* */ +/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */ +/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */ +/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */ +/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */ +/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */ +/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */ +/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/**************************************************************************/ + +#define QOA_IMPLEMENTATION +#define QOA_NO_STDIO + +#include "audio_stream_qoa.h" + +#include "core/io/file_access.h" + +int AudioStreamPlaybackQOA::_mix_internal(AudioFrame *p_buffer, int p_frames) { + if (!active) { + return 0; + } + + int todo = p_frames; + int frames_mixed_this_step = p_frames; + + uint32_t begin_limit = (qoa_stream->loop_mode != AudioStreamQOA::LOOP_DISABLED) ? qoa_stream->loop_begin : 0; + uint32_t end_limit = (qoa_stream->loop_mode != AudioStreamQOA::LOOP_DISABLED) ? qoa_stream->loop_end : qoad->samples; + + while (todo && active) { + if (decoded_len <= decoded_offset) { + // Decode the next or previous QOA frame + data_offset += int(frame_data_len) * increment; + qoa_decode_frame(qoa_stream->data.ptr() + data_offset, frame_data_len, qoad, decoded, &decoded_len); + decoded_offset = increment > 0 ? 0 : decoded_len - 1; + } + + uint32_t dec_index = decoded_offset * qoad->channels; + p_buffer[p_frames - todo][0] = decoded[qoa_stream->stereo ? dec_index++ : dec_index]; + p_buffer[p_frames - todo][1] = decoded[dec_index]; + p_buffer[p_frames - todo] /= 32767.0f; + + --todo; + + if (frames_mixed <= begin_limit + 1) { + // Begin of file or loop + if (qoa_stream->loop_mode == AudioStreamQOA::LOOP_PINGPONG) { + increment = 1; + } else if (qoa_stream->loop_mode == AudioStreamQOA::LOOP_BACKWARD) { + seek(double(end_limit - 1) / qoa_stream->mix_rate); + } + } + + if (frames_mixed >= end_limit - 1) { + // End of file or loop + if (qoa_stream->loop_mode == AudioStreamQOA::LOOP_FORWARD) { + seek(double(begin_limit) / qoa_stream->mix_rate); + } else if (qoa_stream->loop_mode == AudioStreamQOA::LOOP_PINGPONG) { + increment = -1; + } else if (qoa_stream->loop_mode == AudioStreamQOA::LOOP_DISABLED) { + frames_mixed_this_step = p_frames - todo; + //fill remainder with silence + for (int i = p_frames - todo; i < p_frames; i++) { + p_buffer[i] = AudioFrame(0, 0); + } + active = false; + todo = 0; + } + } + + frames_mixed += increment; + decoded_offset += increment; + } + return frames_mixed_this_step; +} + +float AudioStreamPlaybackQOA::get_stream_sampling_rate() { + return qoa_stream->mix_rate; +} + +void AudioStreamPlaybackQOA::start(double p_from_pos) { + active = true; + seek(p_from_pos); + if (qoa_stream->loop_mode == AudioStreamQOA::LOOP_BACKWARD) { + increment = -1; + } + begin_resample(); +} + +void AudioStreamPlaybackQOA::stop() { + active = false; +} + +bool AudioStreamPlaybackQOA::is_playing() const { + return active; +} + +int AudioStreamPlaybackQOA::get_loop_count() const { + return 0; +} + +double AudioStreamPlaybackQOA::get_playback_position() const { + return double(frames_mixed) / qoa_stream->mix_rate; +} + +void AudioStreamPlaybackQOA::seek(double p_time) { + if (!active) { + return; + } + + if (p_time >= qoa_stream->get_length()) { + p_time = 0; + } + + frames_mixed = uint32_t(qoa_stream->mix_rate * p_time); + uint32_t new_data_offset = 8 + frames_mixed / QOA_FRAME_LEN * frame_data_len; + + if (new_data_offset != data_offset) { + qoa_decode_frame(qoa_stream->data.ptr() + new_data_offset, frame_data_len, qoad, decoded, &decoded_len); + } + decoded_offset = frames_mixed % QOA_FRAME_LEN; + data_offset = new_data_offset; +} + +void AudioStreamPlaybackQOA::tag_used_streams() { + qoa_stream->tag_used(get_playback_position()); +} + +AudioStreamPlaybackQOA::~AudioStreamPlaybackQOA() { + if (qoad) { + memfree(qoad); + } + if (decoded) { + memfree(decoded); + } +} + +Ref AudioStreamQOA::instantiate_playback() { + Ref qoas; + + ERR_FAIL_COND_V_MSG(data.is_empty(), qoas, + "This AudioStreamQOA does not have an audio file assigned " + "to it. AudioStreamQOA should not be created from the " + "inspector or with `.new()`. Instead, load an audio file."); + + qoas.instantiate(); + qoas->qoa_stream = Ref(this); + + qoas->qoad = (qoa_desc *)memalloc(sizeof(qoa_desc)); + qoa_decode_header(data.ptr(), QOA_MIN_FILESIZE, qoas->qoad); + + qoas->frame_data_len = qoa_max_frame_size(qoas->qoad); + qoas->decoded = (short *)memalloc(qoas->qoad->channels * QOA_FRAME_LEN * sizeof(short) * 2); + + qoas->data_offset = 0; + qoas->frames_mixed = 0; + qoas->active = false; + + ERR_FAIL_NULL_V(qoas->qoad, Ref()); + + return qoas; +} + +String AudioStreamQOA::get_stream_name() const { + return ""; +} + +void AudioStreamQOA::clear_data() { + data.clear(); +} + +void AudioStreamQOA::set_data(const Vector &p_data) { + int src_data_len = p_data.size(); + const uint8_t *src_datar = p_data.ptr(); + + qoa_desc qoad; + uint32_t ffp = qoa_decode_header(src_datar, src_data_len, &qoad); + ERR_FAIL_COND_MSG(ffp != 8, "Failed to decode QOA header. Make sure it is a valid QOA audio file."); + + stereo = qoad.channels > 1; + mix_rate = qoad.samplerate; + length = float(qoad.samples) / (mix_rate); + clear_data(); + + data.resize(src_data_len); + memcpy(data.ptrw(), src_datar, src_data_len); + data_len = src_data_len; +} + +Vector AudioStreamQOA::get_data() const { + return data; +} + +void AudioStreamQOA::set_loop_mode(LoopMode p_loop_mode) { + loop_mode = p_loop_mode; +} + +AudioStreamQOA::LoopMode AudioStreamQOA::get_loop_mode() const { + return loop_mode; +} + +void AudioStreamQOA::set_loop_begin(int p_frame) { + loop_begin = p_frame; +} + +int AudioStreamQOA::get_loop_begin() const { + return loop_begin; +} + +void AudioStreamQOA::set_loop_end(int p_frame) { + loop_end = p_frame; +} + +int AudioStreamQOA::get_loop_end() const { + return loop_end; +} + +void AudioStreamQOA::set_mix_rate(int p_hz) { + mix_rate = p_hz; +} + +int AudioStreamQOA::get_mix_rate() const { + return mix_rate; +} + +double AudioStreamQOA::get_length() const { + return length; +} + +void AudioStreamQOA::set_stereo(bool p_stereo) { + stereo = p_stereo; +} + +bool AudioStreamQOA::is_stereo() const { + return stereo; +} + +bool AudioStreamQOA::is_monophonic() const { + return false; +} + +void AudioStreamQOA::_bind_methods() { + ClassDB::bind_method(D_METHOD("set_data", "data"), &AudioStreamQOA::set_data); + ClassDB::bind_method(D_METHOD("get_data"), &AudioStreamQOA::get_data); + + ClassDB::bind_method(D_METHOD("set_loop_mode", "loop_mode"), &AudioStreamQOA::set_loop_mode); + ClassDB::bind_method(D_METHOD("get_loop_mode"), &AudioStreamQOA::get_loop_mode); + + ClassDB::bind_method(D_METHOD("set_loop_begin", "seconds"), &AudioStreamQOA::set_loop_begin); + ClassDB::bind_method(D_METHOD("get_loop_begin"), &AudioStreamQOA::get_loop_begin); + + ClassDB::bind_method(D_METHOD("set_loop_end", "seconds"), &AudioStreamQOA::set_loop_end); + ClassDB::bind_method(D_METHOD("get_loop_end"), &AudioStreamQOA::get_loop_end); + + ClassDB::bind_method(D_METHOD("set_mix_rate", "hz"), &AudioStreamQOA::set_mix_rate); + ClassDB::bind_method(D_METHOD("get_mix_rate"), &AudioStreamQOA::get_mix_rate); + + ClassDB::bind_method(D_METHOD("set_stereo", "stereo"), &AudioStreamQOA::set_stereo); + ClassDB::bind_method(D_METHOD("is_stereo"), &AudioStreamQOA::is_stereo); + + ADD_PROPERTY(PropertyInfo(Variant::PACKED_BYTE_ARRAY, "data", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NO_EDITOR), "set_data", "get_data"); + ADD_PROPERTY(PropertyInfo(Variant::INT, "loop_mode", PROPERTY_HINT_ENUM, "Disabled,Forward,Ping-Pong,Backward"), "set_loop_mode", "get_loop_mode"); + ADD_PROPERTY(PropertyInfo(Variant::INT, "loop_begin"), "set_loop_begin", "get_loop_begin"); + ADD_PROPERTY(PropertyInfo(Variant::INT, "loop_end"), "set_loop_end", "get_loop_end"); + ADD_PROPERTY(PropertyInfo(Variant::INT, "mix_rate"), "set_mix_rate", "get_mix_rate"); + ADD_PROPERTY(PropertyInfo(Variant::BOOL, "stereo"), "set_stereo", "is_stereo"); + + BIND_ENUM_CONSTANT(LOOP_DISABLED); + BIND_ENUM_CONSTANT(LOOP_FORWARD); + BIND_ENUM_CONSTANT(LOOP_PINGPONG); + BIND_ENUM_CONSTANT(LOOP_BACKWARD); +} + +AudioStreamQOA::AudioStreamQOA() { +} + +AudioStreamQOA::~AudioStreamQOA() { + clear_data(); +} diff --git a/modules/qoa/audio_stream_qoa.h b/modules/qoa/audio_stream_qoa.h new file mode 100644 index 000000000000..eba6cedcabc3 --- /dev/null +++ b/modules/qoa/audio_stream_qoa.h @@ -0,0 +1,142 @@ +/**************************************************************************/ +/* audio_stream_qoa.h */ +/**************************************************************************/ +/* This file is part of: */ +/* GODOT ENGINE */ +/* https://godotengine.org */ +/**************************************************************************/ +/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */ +/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */ +/* */ +/* Permission is hereby granted, free of charge, to any person obtaining */ +/* a copy of this software and associated documentation files (the */ +/* "Software"), to deal in the Software without restriction, including */ +/* without limitation the rights to use, copy, modify, merge, publish, */ +/* distribute, sublicense, and/or sell copies of the Software, and to */ +/* permit persons to whom the Software is furnished to do so, subject to */ +/* the following conditions: */ +/* */ +/* The above copyright notice and this permission notice shall be */ +/* included in all copies or substantial portions of the Software. */ +/* */ +/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */ +/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */ +/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */ +/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */ +/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */ +/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */ +/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/**************************************************************************/ + +#ifndef AUDIO_STREAM_QOA_H +#define AUDIO_STREAM_QOA_H + +#include "core/io/resource_loader.h" +#include "servers/audio/audio_stream.h" + +#include "thirdparty/misc/qoa.h" + +class AudioStreamQOA; + +class AudioStreamPlaybackQOA : public AudioStreamPlaybackResampled { + GDCLASS(AudioStreamPlaybackQOA, AudioStreamPlaybackResampled); + + qoa_desc *qoad = nullptr; + uint32_t data_offset = 0; + uint32_t frames_mixed = 0; + uint32_t frame_data_len = 0; + int16_t *decoded = nullptr; + uint32_t decoded_len = 0; + uint32_t decoded_offset = 0; + + bool active = false; + int increment = 1; + + friend class AudioStreamQOA; + + Ref qoa_stream; + +protected: + virtual int _mix_internal(AudioFrame *p_buffer, int p_frames) override; + virtual float get_stream_sampling_rate() override; + +public: + virtual void start(double p_from_pos = 0.0) override; + virtual void stop() override; + virtual bool is_playing() const override; + + virtual int get_loop_count() const override; //times it looped + + virtual double get_playback_position() const override; + virtual void seek(double p_time) override; + + virtual void tag_used_streams() override; + + AudioStreamPlaybackQOA() {} + ~AudioStreamPlaybackQOA(); +}; + +class AudioStreamQOA : public AudioStream { + GDCLASS(AudioStreamQOA, AudioStream); + OBJ_SAVE_TYPE(AudioStream) //children are all saved as AudioStream, so they can be exchanged + RES_BASE_EXTENSION("qoastr"); + +public: + // Keep the ResourceImporterQOA `edit/loop_mode` enum hint in sync with these options. + enum LoopMode { + LOOP_DISABLED, + LOOP_FORWARD, + LOOP_PINGPONG, + LOOP_BACKWARD, + }; + +private: + friend class AudioStreamPlaybackQOA; + + PackedByteArray data; + uint32_t data_len = 0; + + LoopMode loop_mode = LOOP_DISABLED; + bool stereo = false; + float length = 0.0; + int loop_begin = 0; + int loop_end = -1; + int mix_rate = 44100; + void clear_data(); + +protected: + static void _bind_methods(); + +public: + void set_loop_mode(LoopMode p_loop_mode); + LoopMode get_loop_mode() const; + + void set_loop_begin(int p_frame); + int get_loop_begin() const; + + void set_loop_end(int p_frame); + int get_loop_end() const; + + void set_mix_rate(int p_hz); + int get_mix_rate() const; + + void set_stereo(bool p_stereo); + bool is_stereo() const; + + virtual double get_length() const override; + + virtual bool is_monophonic() const override; + + void set_data(const Vector &p_data); + Vector get_data() const; + + virtual Ref instantiate_playback() override; + virtual String get_stream_name() const override; + + AudioStreamQOA(); + virtual ~AudioStreamQOA(); +}; + +VARIANT_ENUM_CAST(AudioStreamQOA::LoopMode) + +#endif // AUDIO_STREAM_QOA_H diff --git a/modules/qoa/config.py b/modules/qoa/config.py new file mode 100644 index 000000000000..e752ff12f2cd --- /dev/null +++ b/modules/qoa/config.py @@ -0,0 +1,17 @@ +def can_build(env, platform): + return True + + +def configure(env): + pass + + +def get_doc_classes(): + return [ + "AudioStreamQOA", + "ResourceImporterQOA", + ] + + +def get_doc_path(): + return "doc_classes" diff --git a/modules/qoa/doc_classes/AudioStreamQOA.xml b/modules/qoa/doc_classes/AudioStreamQOA.xml new file mode 100644 index 000000000000..480f74cbd67f --- /dev/null +++ b/modules/qoa/doc_classes/AudioStreamQOA.xml @@ -0,0 +1,66 @@ + + + + QOA audio stream driver. + + + [url=https://qoaformat.org/]QOA[/url] audio stream driver. See [member data] if you want to load a QOA file at run-time. + + + + + + Contains the audio data in bytes. + You can load a file without having to import it beforehand using the code snippet below. Keep in mind that this snippet loads the whole file into memory and may not be ideal for huge files (hundreds of megabytes or more). + [codeblocks] + [gdscript] + func load_qoa(path): + var file = FileAccess.open(path, FileAccess.READ) + var sound = AudioStreamQOA.new() + sound.data = file.get_buffer(file.get_length()) + return sound + [/gdscript] + [csharp] + public AudioStreamQoa LoadQoa(string path) + { + using var file = FileAccess.Open(path, FileAccess.ModeFlags.Read); + var sound = new AudioStreamQoa(); + sound.Data = file.GetBuffer(file.GetLength()); + return sound; + } + [/csharp] + [/codeblocks] + + + The loop start point (in number of samples, relative to the beginning of the sample). If imported from a WAV file, this information will be read automatically if present. + + + The loop end point (in number of samples, relative to the beginning of the sample). If imported from a WAV file, this information will be read automatically if present. + + + The loop mode. If imported from a WAV file, this information will be read automatically. See [enum LoopMode] constants for values. + + + The sample rate for mixing this audio. Higher values require more storage space, but result in better quality. + In games, common sample rates in use are [code]11025[/code], [code]16000[/code], [code]22050[/code], [code]32000[/code], [code]44100[/code], and [code]48000[/code]. + According to the [url=https://en.wikipedia.org/wiki/Nyquist%E2%80%93Shannon_sampling_theorem]Nyquist-Shannon sampling theorem[/url], there is no quality difference to human hearing when going past 40,000 Hz (since most humans can only hear up to ~20,000 Hz, often less). If you are using lower-pitched sounds such as voices, lower sample rates such as [code]32000[/code] or [code]22050[/code] may be usable with no loss in quality. + + + If [code]true[/code], audio is stereo. + + + + + Audio does not loop. + + + Audio loops the data between [member loop_begin] and [member loop_end], playing forward only. + + + Audio loops the data between [member loop_begin] and [member loop_end], playing back and forth. + + + Audio loops the data between [member loop_begin] and [member loop_end], playing backward only. + + + diff --git a/modules/qoa/doc_classes/ResourceImporterQOA.xml b/modules/qoa/doc_classes/ResourceImporterQOA.xml new file mode 100644 index 000000000000..649cc11a1565 --- /dev/null +++ b/modules/qoa/doc_classes/ResourceImporterQOA.xml @@ -0,0 +1,44 @@ + + + + Imports a QOA audio file or converts a WAV audio file for playback. + + + QOA is a lossy audio format, with worse audio quality compared to [ResourceImporterOggVorbis] and [ResourceImporterMP3] at a reasonable bitrate, but significantly better than [ResourceImporterWAV] when compressed as IMA-ADPCM. + It's recommended to use QOA when you need to play a lot of simultaneous sound effects, but also save memory. + You may import WAV files into QOA by selecting "Quite OK Audio" in the Import As dropdown. + + + $DOCS_URL/tutorials/assets_pipeline/importing_audio_samples.html + + + + The begin loop point to use when [member edit/loop_mode] is enabled. This is set in seconds after the beginning of the audio file. + + + The end loop point to use when [member edit/loop_mode] is enabled. This is set in seconds after the beginning of the audio file. A value of [code]-1[/code] uses the end of the audio file as the end loop point. + + + Controls how audio should loop. If imported from WAV, this is automatically read from the metadata on import. + [b]Disabled:[/b] Don't loop audio, even if metadata indicates the file should be played back looping. + [b]Forward:[/b] Standard audio looping. + [b]Note:[/b] In [AudioStreamPlayer], the [signal AudioStreamPlayer.finished] signal won't be emitted for looping audio when it reaches the end of the audio file, as the audio will keep playing indefinitely. + + + WAV only. If [code]true[/code], normalize the audio volume so that its peak volume is equal to 0 dB. When enabled, normalization will make audio sound louder depending on its original peak volume. + + + WAV only. If [code]true[/code], automatically trim the beginning and end of the audio if it's lower than -50 dB after normalization (see [member edit/normalize]). This prevents having files with silence at the beginning or end, which increases their size unnecessarily and adds latency to the moment they are played back. A fade-in/fade-out period of 500 samples is also used during trimming to avoid audible pops. + + + WAV only. If set to a value greater than [code]0[/code], forces the audio's sample rate to be reduced to a value lower than or equal to the value specified in [member force/max_rate_hz]. + This can decrease file size noticeably on certain sounds, without impacting quality depending on the actual sound's contents. See [url=$DOCS_URL/tutorials/assets_pipeline/importing_audio_samples.html#doc-importing-audio-samples-best-practices]Best practices[/url] for more information. + + + WAV only. The frequency to limit the imported audio sample to (in Hz). Only effective if [member force/max_rate] is [code]true[/code]. + + + WAV only. If [code]true[/code], forces the imported audio to be mono if the source file is stereo. This decreases the file size by 50% by merging the two channels into one. + + + diff --git a/modules/qoa/register_types.cpp b/modules/qoa/register_types.cpp new file mode 100644 index 000000000000..4fe262d3ff04 --- /dev/null +++ b/modules/qoa/register_types.cpp @@ -0,0 +1,68 @@ +/**************************************************************************/ +/* register_types.cpp */ +/**************************************************************************/ +/* This file is part of: */ +/* GODOT ENGINE */ +/* https://godotengine.org */ +/**************************************************************************/ +/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */ +/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */ +/* */ +/* Permission is hereby granted, free of charge, to any person obtaining */ +/* a copy of this software and associated documentation files (the */ +/* "Software"), to deal in the Software without restriction, including */ +/* without limitation the rights to use, copy, modify, merge, publish, */ +/* distribute, sublicense, and/or sell copies of the Software, and to */ +/* permit persons to whom the Software is furnished to do so, subject to */ +/* the following conditions: */ +/* */ +/* The above copyright notice and this permission notice shall be */ +/* included in all copies or substantial portions of the Software. */ +/* */ +/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */ +/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */ +/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */ +/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */ +/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */ +/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */ +/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/**************************************************************************/ + +#include "register_types.h" + +#include "audio_stream_qoa.h" + +#ifdef TOOLS_ENABLED +#include "core/config/engine.h" +#include "resource_importer_qoa.h" +#endif + +void initialize_qoa_module(ModuleInitializationLevel p_level) { + if (p_level != MODULE_INITIALIZATION_LEVEL_SCENE) { + return; + } + +#ifdef TOOLS_ENABLED + if (Engine::get_singleton()->is_editor_hint()) { + Ref qoa_import; + qoa_import.instantiate(); + ResourceFormatImporter::get_singleton()->add_importer(qoa_import); + } + + ClassDB::APIType prev_api = ClassDB::get_current_api(); + ClassDB::set_current_api(ClassDB::API_EDITOR); + + // Required to document import options in the class reference. + GDREGISTER_CLASS(ResourceImporterQOA); + + ClassDB::set_current_api(prev_api); +#endif + + GDREGISTER_CLASS(AudioStreamQOA); +} + +void uninitialize_qoa_module(ModuleInitializationLevel p_level) { + if (p_level != MODULE_INITIALIZATION_LEVEL_SCENE) { + return; + } +} diff --git a/modules/qoa/register_types.h b/modules/qoa/register_types.h new file mode 100644 index 000000000000..9e57178edfe5 --- /dev/null +++ b/modules/qoa/register_types.h @@ -0,0 +1,39 @@ +/**************************************************************************/ +/* register_types.h */ +/**************************************************************************/ +/* This file is part of: */ +/* GODOT ENGINE */ +/* https://godotengine.org */ +/**************************************************************************/ +/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */ +/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */ +/* */ +/* Permission is hereby granted, free of charge, to any person obtaining */ +/* a copy of this software and associated documentation files (the */ +/* "Software"), to deal in the Software without restriction, including */ +/* without limitation the rights to use, copy, modify, merge, publish, */ +/* distribute, sublicense, and/or sell copies of the Software, and to */ +/* permit persons to whom the Software is furnished to do so, subject to */ +/* the following conditions: */ +/* */ +/* The above copyright notice and this permission notice shall be */ +/* included in all copies or substantial portions of the Software. */ +/* */ +/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */ +/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */ +/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */ +/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */ +/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */ +/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */ +/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/**************************************************************************/ + +#ifndef QOA_REGISTER_TYPES_H +#define QOA_REGISTER_TYPES_H + +#include "modules/register_module_types.h" + +void initialize_qoa_module(ModuleInitializationLevel p_level); +void uninitialize_qoa_module(ModuleInitializationLevel p_level); + +#endif // QOA_REGISTER_TYPES_H diff --git a/modules/qoa/resource_importer_qoa.cpp b/modules/qoa/resource_importer_qoa.cpp new file mode 100644 index 000000000000..739b219b1bdb --- /dev/null +++ b/modules/qoa/resource_importer_qoa.cpp @@ -0,0 +1,476 @@ +/**************************************************************************/ +/* resource_importer_qoa.cpp */ +/**************************************************************************/ +/* This file is part of: */ +/* GODOT ENGINE */ +/* https://godotengine.org */ +/**************************************************************************/ +/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */ +/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */ +/* */ +/* Permission is hereby granted, free of charge, to any person obtaining */ +/* a copy of this software and associated documentation files (the */ +/* "Software"), to deal in the Software without restriction, including */ +/* without limitation the rights to use, copy, modify, merge, publish, */ +/* distribute, sublicense, and/or sell copies of the Software, and to */ +/* permit persons to whom the Software is furnished to do so, subject to */ +/* the following conditions: */ +/* */ +/* The above copyright notice and this permission notice shall be */ +/* included in all copies or substantial portions of the Software. */ +/* */ +/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */ +/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */ +/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */ +/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */ +/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */ +/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */ +/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/**************************************************************************/ + +#define QOA_IMPLEMENTATION +#define QOA_NO_STDIO + +#include "resource_importer_qoa.h" + +#include "core/io/file_access.h" +#include "core/io/marshalls.h" +#include "core/io/resource_saver.h" + +const float TRIM_DB_LIMIT = -50; +const int TRIM_FADE_OUT_FRAMES = 500; + +String ResourceImporterQOA::get_importer_name() const { + return "qoa"; +} + +String ResourceImporterQOA::get_visible_name() const { + return "Quite OK Audio"; +} + +void ResourceImporterQOA::get_recognized_extensions(List *p_extensions) const { + p_extensions->push_back("qoa"); + p_extensions->push_back("wav"); +} + +String ResourceImporterQOA::get_save_extension() const { + return "qoastr"; +} + +String ResourceImporterQOA::get_resource_type() const { + return "AudioStreamQOA"; +} + +bool ResourceImporterQOA::get_option_visibility(const String &p_path, const String &p_option, const HashMap &p_options) const { + if (check_qoa(p_path)) { + // These options only apply for WAV files. + if (p_option == "force/mono" || p_option == "force/max_rate" || p_option == "force/max_rate_hz" || p_option == "edit/trim" || p_option == "edit/normalize") { + return false; + } + } + + if (p_option == "force/max_rate_hz" && !bool(p_options["force/max_rate"])) { + return false; + } + + // Don't show begin/end loop points if loop mode is auto-detected or disabled. + if ((int)p_options["edit/loop_mode"] < 2 && (p_option == "edit/loop_begin" || p_option == "edit/loop_end")) { + return false; + } + + return true; +} + +int ResourceImporterQOA::get_preset_count() const { + return 0; +} + +String ResourceImporterQOA::get_preset_name(int p_idx) const { + return String(); +} + +void ResourceImporterQOA::get_import_options(const String &p_path, List *r_options, int p_preset) const { + r_options->push_back(ImportOption(PropertyInfo(Variant::BOOL, "force/mono"), false)); + r_options->push_back(ImportOption(PropertyInfo(Variant::BOOL, "force/max_rate", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_DEFAULT | PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED), false)); + r_options->push_back(ImportOption(PropertyInfo(Variant::FLOAT, "force/max_rate_hz", PROPERTY_HINT_RANGE, "11025,192000,1,exp"), 44100)); + r_options->push_back(ImportOption(PropertyInfo(Variant::BOOL, "edit/trim"), false)); + r_options->push_back(ImportOption(PropertyInfo(Variant::BOOL, "edit/normalize"), false)); + // Keep the `edit/loop_mode` enum in sync with AudioStreamQOA::LoopMode (note: +1 offset due to "Detect From WAV"). + r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "edit/loop_mode", PROPERTY_HINT_ENUM, "Detect From WAV,Disabled,Forward,Ping-Pong,Backward", PROPERTY_USAGE_DEFAULT | PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED), 0)); + r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "edit/loop_begin"), 0)); + r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "edit/loop_end"), -1)); +} + +Ref ResourceImporterQOA::import_qoa(const String &p_path, const HashMap &p_options) { + Ref file = FileAccess::open(p_path, FileAccess::READ); + ERR_FAIL_COND_V(file.is_null(), Ref()); + + int import_loop_mode = p_options["edit/loop_mode"]; + AudioStreamQOA::LoopMode loop_mode = AudioStreamQOA::LOOP_DISABLED; + int loop_begin = import_loop_mode > 1 ? (int)p_options["edit/loop_begin"] : 0; + int loop_end = import_loop_mode > 1 ? (int)p_options["edit/loop_end"] : 0; + int frames = 0; + + Vector qoa_data; + uint32_t len; + + if (check_qoa(p_path)) { + if (import_loop_mode > 1) { + loop_mode = (AudioStreamQOA::LoopMode)(import_loop_mode - 1); + } + file->seek(0); + len = file->get_length(); + qoa_data.resize(len); + uint8_t *w = qoa_data.ptrw(); + + file->get_buffer(w, len); + + qoa_desc qd; + qd.samples = 0; + qoa_decode_header(w, len, &qd); + frames = qd.samples; + + } else { // WAV + char riff[5]; + riff[4] = 0; + file->get_buffer((uint8_t *)&riff, 4); //RIFF + + if (riff[0] != 'R' || riff[1] != 'I' || riff[2] != 'F' || riff[3] != 'F') { + ERR_FAIL_V_MSG(Ref(), vformat("Not a WAV file. File should start with 'RIFF', but found '%s', in file of size %d bytes.", riff, file->get_length())); + } + + file->get_32(); + + char wave[5]; + wave[4] = 0; + file->get_buffer((uint8_t *)&wave, 4); //WAVE + + if (wave[0] != 'W' || wave[1] != 'A' || wave[2] != 'V' || wave[3] != 'E') { + ERR_FAIL_V_MSG(Ref(), vformat("Not a WAV file. File should start with 'WAVE', but found '%s', in file of size %d bytes.", wave, file->get_length())); + } + + // Let users override potential loop points from the WAV. + // We parse the WAV loop points only with "Detect From WAV" (0). + + int format_bits = 0; + int format_channels = 0; + + uint16_t compression_code = 1; + bool format_found = false; + bool data_found = false; + int format_freq = 0; + + Vector data; + + while (!file->eof_reached()) { + /* chunk */ + char chunk_id[4]; + file->get_buffer((uint8_t *)&chunk_id, 4); //RIFF + + /* chunk size */ + uint32_t chunksize = file->get_32(); + uint32_t file_pos = file->get_position(); //save file pos, so we can skip to next chunk safely + + if (file->eof_reached()) { + //ERR_PRINT("EOF REACH"); + break; + } + + if (chunk_id[0] == 'f' && chunk_id[1] == 'm' && chunk_id[2] == 't' && chunk_id[3] == ' ' && !format_found) { + /* IS FORMAT CHUNK */ + + //Issue: #7755 : Not a bug - usage of other formats (format codes) are unsupported in current importer version. + //Consider revision for engine version 3.0 + compression_code = file->get_16(); + ERR_FAIL_COND_V_MSG(compression_code != 1 && compression_code != 3, Ref(), "Format not supported for WAVE file (not PCM). Save WAVE files as uncompressed PCM or IEEE float instead."); + + format_channels = file->get_16(); + ERR_FAIL_COND_V_MSG(format_channels != 1 && format_channels != 2, Ref(), "Format not supported for WAVE file (not stereo or mono)."); + + format_freq = file->get_32(); //sampling rate + + file->get_32(); // average bits/second (unused) + file->get_16(); // block align (unused) + format_bits = file->get_16(); // bits per sample + ERR_FAIL_COND_V_MSG(format_bits % 8 || format_bits == 0, Ref(), "Invalid amount of bits in the sample (should be one of 8, 16, 24 or 32)."); + ERR_FAIL_COND_V_MSG(compression_code == 3 && format_bits % 32, Ref(), "Invalid amount of bits in the IEEE float sample (should be 32 or 64)."); + + /* Don't need anything else, continue */ + format_found = true; + } + + if (chunk_id[0] == 'd' && chunk_id[1] == 'a' && chunk_id[2] == 't' && chunk_id[3] == 'a' && !data_found) { + /* IS DATA CHUNK */ + data_found = true; + + ERR_BREAK_MSG(!format_found, "'data' chunk before 'format' chunk found."); + + frames = chunksize; + + ERR_FAIL_COND_V(format_channels == 0, Ref()); + + frames /= format_channels; + frames /= (format_bits >> 3); + + data.resize(frames * format_channels); + + if (compression_code == 1) { + if (format_bits == 8) { + for (int i = 0; i < frames * format_channels; i++) { + // 8 bit samples are UNSIGNED + + data.write[i] = int8_t(file->get_8() - 128) / 128.f; + } + } else if (format_bits == 16) { + for (int i = 0; i < frames * format_channels; i++) { + //16 bit SIGNED + + data.write[i] = int16_t(file->get_16()) / 32768.f; + } + } else { + for (int i = 0; i < frames * format_channels; i++) { + //16+ bits samples are SIGNED + // if sample is > 16 bits, just read extra bytes + + uint32_t s = 0; + for (int b = 0; b < (format_bits >> 3); b++) { + s |= ((uint32_t)file->get_8()) << (b * 8); + } + s <<= (32 - format_bits); + + data.write[i] = (int32_t(s) >> 16) / 32768.f; + } + } + } else if (compression_code == 3) { + if (format_bits == 32) { + for (int i = 0; i < frames * format_channels; i++) { + //32 bit IEEE Float + + data.write[i] = file->get_float(); + } + } else if (format_bits == 64) { + for (int i = 0; i < frames * format_channels; i++) { + //64 bit IEEE Float + + data.write[i] = file->get_double(); + } + } + } + ERR_FAIL_COND_V_MSG(file->eof_reached(), Ref(), "Premature end of file."); + } + + if (import_loop_mode == 0 && chunk_id[0] == 's' && chunk_id[1] == 'm' && chunk_id[2] == 'p' && chunk_id[3] == 'l') { + // Loop point info! + + /** + * Consider exploring next document: + * http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/RIFFNEW.pdf + * Especially on page: + * 16 - 17 + * Timestamp: + * 22:38 06.07.2017 GMT + **/ + + for (int i = 0; i < 10; i++) { + file->get_32(); // i wish to know why should i do this... no doc! + } + + // only read 0x00 (loop forward), 0x01 (loop ping-pong) and 0x02 (loop backward) + // Skip anything else because it's not supported, reserved for future uses or sampler specific + // from https://sites.google.com/site/musicgapi/technical-documents/wav-file-format#smpl (loop type values table) + int loop_type = file->get_32(); + if (loop_type == 0x00 || loop_type == 0x01 || loop_type == 0x02) { + if (loop_type == 0x00) { + loop_mode = AudioStreamQOA::LOOP_FORWARD; + } else if (loop_type == 0x01) { + loop_mode = AudioStreamQOA::LOOP_PINGPONG; + } else if (loop_type == 0x02) { + loop_mode = AudioStreamQOA::LOOP_BACKWARD; + } + loop_begin = file->get_32(); + loop_end = file->get_32(); + } + } + + file->seek(file_pos + chunksize + (chunksize & 1)); + } + + bool limit_rate = p_options["force/max_rate"]; + int limit_rate_hz = p_options["force/max_rate_hz"]; + if (limit_rate && format_freq > limit_rate_hz && format_freq > 0 && frames > 0) { + // resample! + int new_data_frames = (int)(frames * (float)limit_rate_hz / format_freq); + + Vector new_data; + new_data.resize(new_data_frames * format_channels); + for (int c = 0; c < format_channels; c++) { + float frac = .0f; + int ipos = 0; + + for (int i = 0; i < new_data_frames; i++) { + // Cubic interpolation should be enough. + + float y0 = data[MAX(0, ipos - 1) * format_channels + c]; + float y1 = data[ipos * format_channels + c]; + float y2 = data[MIN(frames - 1, ipos + 1) * format_channels + c]; + float y3 = data[MIN(frames - 1, ipos + 2) * format_channels + c]; + + new_data.write[i * format_channels + c] = Math::cubic_interpolate(y1, y2, y0, y3, frac); + + // update position and always keep fractional part within ]0...1] + // in order to avoid 32bit floating point precision errors + + frac += (float)format_freq / limit_rate_hz; + int tpos = (int)Math::floor(frac); + ipos += tpos; + frac -= tpos; + } + } + + if (loop_mode) { + loop_begin = (int)(loop_begin * (float)new_data_frames / frames); + loop_end = (int)(loop_end * (float)new_data_frames / frames); + } + + data = new_data; + format_freq = limit_rate_hz; + frames = new_data_frames; + } + + bool normalize = p_options["edit/normalize"]; + + if (normalize) { + float max = 0; + for (int i = 0; i < data.size(); i++) { + float amp = Math::abs(data[i]); + if (amp > max) { + max = amp; + } + } + + if (max > 0) { + float mult = 1.0 / max; + for (int i = 0; i < data.size(); i++) { + data.write[i] *= mult; + } + } + } + + bool trim = p_options["edit/trim"]; + + if (trim && (loop_mode == AudioStreamQOA::LOOP_DISABLED) && format_channels > 0) { + int first = 0; + int last = (frames / format_channels) - 1; + bool found = false; + float limit = Math::db_to_linear(TRIM_DB_LIMIT); + + for (int i = 0; i < data.size() / format_channels; i++) { + float amp_channel_sum = 0; + for (int j = 0; j < format_channels; j++) { + amp_channel_sum += Math::abs(data[(i * format_channels) + j]); + } + + float amp = Math::abs(amp_channel_sum / format_channels); + + if (!found && amp > limit) { + first = i; + found = true; + } + + if (found && amp > limit) { + last = i; + } + } + + if (first < last) { + Vector new_data; + new_data.resize((last - first) * format_channels); + for (int i = first; i < last; i++) { + float fade_out_mult = 1; + + if (last - i < TRIM_FADE_OUT_FRAMES) { + fade_out_mult = ((float)(last - i - 1) / (float)TRIM_FADE_OUT_FRAMES); + } + + for (int j = 0; j < format_channels; j++) { + new_data.write[((i - first) * format_channels) + j] = data[(i * format_channels) + j] * fade_out_mult; + } + } + + data = new_data; + frames = data.size() / format_channels; + } + } + + bool force_mono = p_options["force/mono"]; + + if (force_mono && format_channels == 2) { + Vector new_data; + new_data.resize(data.size() / 2); + for (int i = 0; i < frames; i++) { + new_data.write[i] = (data[i * 2 + 0] + data[i * 2 + 1]) / 2.0; + } + + data = new_data; + format_channels = 1; + } + + Vector wav_data; + // Enforce 16 bit samples + wav_data.resize(data.size() * 2); + { + uint8_t *w = wav_data.ptrw(); + + int ds = data.size(); + for (int i = 0; i < ds; i++) { + int16_t v = CLAMP(data[i] * 32768, -32768, 32767); + encode_uint16(v, &w[i * 2]); + } + } + + qoa_desc desc; + + desc.samplerate = format_freq; + desc.samples = frames; + desc.channels = format_channels; + + void *encoded = qoa_encode((short *)wav_data.ptrw(), &desc, &len); + + qoa_data.resize(len); + memcpy(qoa_data.ptrw(), encoded, len); + } + + if (import_loop_mode >= 2) { + loop_mode = (AudioStreamQOA::LoopMode)(import_loop_mode - 1); + // Wrap around to max frames, so `-1` can be used to select the end, etc. + if (loop_begin < 0) { + loop_begin = CLAMP(loop_begin + frames + 1, 0, frames); + } + if (loop_end < 0) { + loop_end = CLAMP(loop_end + frames + 1, 0, frames); + } + } + + Ref qoa_stream; + qoa_stream.instantiate(); + + qoa_stream->set_data(qoa_data); + qoa_stream->set_loop_mode(loop_mode); + qoa_stream->set_loop_begin(loop_begin); + qoa_stream->set_loop_end(loop_end); + ERR_FAIL_COND_V(qoa_stream->get_data().is_empty(), Ref()); + + return qoa_stream; +} + +Error ResourceImporterQOA::import(const String &p_source_file, const String &p_save_path, const HashMap &p_options, List *r_platform_variants, List *r_gen_files, Variant *r_metadata) { + Ref qoa_stream = import_qoa(p_source_file, p_options); + if (qoa_stream.is_null()) { + return ERR_CANT_OPEN; + } + + return ResourceSaver::save(qoa_stream, p_save_path + ".qoastr"); +} + +ResourceImporterQOA::ResourceImporterQOA() { +} diff --git a/modules/qoa/resource_importer_qoa.h b/modules/qoa/resource_importer_qoa.h new file mode 100644 index 000000000000..a65e6e56afd9 --- /dev/null +++ b/modules/qoa/resource_importer_qoa.h @@ -0,0 +1,63 @@ +/**************************************************************************/ +/* resource_importer_qoa.h */ +/**************************************************************************/ +/* This file is part of: */ +/* GODOT ENGINE */ +/* https://godotengine.org */ +/**************************************************************************/ +/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */ +/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */ +/* */ +/* Permission is hereby granted, free of charge, to any person obtaining */ +/* a copy of this software and associated documentation files (the */ +/* "Software"), to deal in the Software without restriction, including */ +/* without limitation the rights to use, copy, modify, merge, publish, */ +/* distribute, sublicense, and/or sell copies of the Software, and to */ +/* permit persons to whom the Software is furnished to do so, subject to */ +/* the following conditions: */ +/* */ +/* The above copyright notice and this permission notice shall be */ +/* included in all copies or substantial portions of the Software. */ +/* */ +/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */ +/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */ +/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */ +/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */ +/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */ +/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */ +/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/**************************************************************************/ + +#ifndef RESOURCE_IMPORTER_QOA_H +#define RESOURCE_IMPORTER_QOA_H + +#include "audio_stream_qoa.h" + +#include "core/io/resource_importer.h" + +class ResourceImporterQOA : public ResourceImporter { + GDCLASS(ResourceImporterQOA, ResourceImporter); + +public: + virtual String get_importer_name() const override; + virtual String get_visible_name() const override; + virtual void get_recognized_extensions(List *p_extensions) const override; + virtual String get_save_extension() const override; + virtual String get_resource_type() const override; + virtual float get_priority() const override { return 0.9; } // For WAVs, decrease priority so ResourceImporterWAV is used by default. + + virtual int get_preset_count() const override; + virtual String get_preset_name(int p_idx) const override; + + virtual void get_import_options(const String &p_path, List *r_options, int p_preset = 0) const override; + virtual bool get_option_visibility(const String &p_path, const String &p_option, const HashMap &p_options) const override; + + static bool check_qoa(const String &p_path) { return p_path.get_extension().to_lower() == "qoa"; } + static Ref import_qoa(const String &p_path, const HashMap &p_options); + + virtual Error import(const String &p_source_file, const String &p_save_path, const HashMap &p_options, List *r_platform_variants, List *r_gen_files = nullptr, Variant *r_metadata = nullptr) override; + + ResourceImporterQOA(); +}; + +#endif // RESOURCE_IMPORTER_QOA_H diff --git a/modules/vorbis/doc_classes/ResourceImporterOggVorbis.xml b/modules/vorbis/doc_classes/ResourceImporterOggVorbis.xml index 8ae63140f508..e987750a0eb0 100644 --- a/modules/vorbis/doc_classes/ResourceImporterOggVorbis.xml +++ b/modules/vorbis/doc_classes/ResourceImporterOggVorbis.xml @@ -6,7 +6,7 @@ Ogg Vorbis is a lossy audio format, with better audio quality compared to [ResourceImporterMP3] at a given bitrate. In most cases, it's recommended to use Ogg Vorbis over MP3. However, if you're using an MP3 sound source with no higher quality source available, then it's recommended to use the MP3 file directly to avoid double lossy compression. - Ogg Vorbis requires more CPU to decode than [ResourceImporterWAV]. If you need to play a lot of simultaneous sounds, it's recommended to use WAV for those sounds instead, especially if targeting low-end devices. + Ogg Vorbis requires more CPU to decode than [ResourceImporterWAV] and [ResourceImporterQOA]. If you need to play a lot of simultaneous sounds, it's recommended to use WAV or QOA for those sounds instead, especially if targeting low-end devices. $DOCS_URL/tutorials/assets_pipeline/importing_audio_samples.html diff --git a/thirdparty/README.md b/thirdparty/README.md index 0520440e52af..8c373d560288 100644 --- a/thirdparty/README.md +++ b/thirdparty/README.md @@ -664,6 +664,11 @@ Collection of single-file libraries used in Godot components. * Version: git (7bdffb428b2b19ad1c43aa44c714dcc104177e84, 2021) * Modifications: Change from STL to Godot types (see provided patch). * License: MIT +- `qoa.h` + * Upstream: https://github.com/phoboslab/qoa + * Version: git (e4c751d61af2c395ea828c5888e728c1953bf09f, 2024) + * Modifications: Inlined functions and patched compiler warnings. + * License: MIT - `r128.{c,h}` * Upstream: https://github.com/fahickman/r128 * Version: git (6fc177671c47640d5bb69af10cf4ee91050015a1, 2023) diff --git a/thirdparty/misc/patches/qoa-inline-werror-fix.patch b/thirdparty/misc/patches/qoa-inline-werror-fix.patch new file mode 100644 index 000000000000..fa9c3e4fb0df --- /dev/null +++ b/thirdparty/misc/patches/qoa-inline-werror-fix.patch @@ -0,0 +1,288 @@ +diff --git a/qoa.h b/qoa.h +index aa8fb59434..242e7d8c81 100644 +--- a/qoa.h ++++ b/qoa.h +@@ -140,14 +140,14 @@ typedef struct { + #endif + } qoa_desc; + +-unsigned int qoa_encode_header(qoa_desc *qoa, unsigned char *bytes); +-unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned int frame_len, unsigned char *bytes); +-void *qoa_encode(const short *sample_data, qoa_desc *qoa, unsigned int *out_len); ++//unsigned int qoa_encode_header(qoa_desc *qoa, unsigned char *bytes); ++//unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned int frame_len, unsigned char *bytes); ++//void *qoa_encode(const short *sample_data, qoa_desc *qoa, unsigned int *out_len); + +-unsigned int qoa_max_frame_size(qoa_desc *qoa); +-unsigned int qoa_decode_header(const unsigned char *bytes, int size, qoa_desc *qoa); +-unsigned int qoa_decode_frame(const unsigned char *bytes, unsigned int size, qoa_desc *qoa, short *sample_data, unsigned int *frame_len); +-short *qoa_decode(const unsigned char *bytes, int size, qoa_desc *file); ++//unsigned int qoa_max_frame_size(qoa_desc *qoa); ++//unsigned int qoa_decode_header(const unsigned char *bytes, int size, qoa_desc *qoa); ++//unsigned int qoa_decode_frame(const unsigned char *bytes, unsigned int size, qoa_desc *qoa, short *sample_data, unsigned int *frame_len); ++//short *qoa_decode(const unsigned char *bytes, int size, qoa_desc *file); + + #ifndef QOA_NO_STDIO + +@@ -298,7 +298,7 @@ static inline int qoa_div(int v, int scalefactor) { + return n; + } + +-static inline int qoa_clamp(int v, int min, int max) { ++static int qoa_clamp(int v, int min, int max) { + if (v < min) { return min; } + if (v > max) { return max; } + return v; +@@ -308,7 +308,7 @@ static inline int qoa_clamp(int v, int min, int max) { + performance quite a bit. The extra if() statement works nicely with the CPUs + branch prediction as this branch is rarely taken. */ + +-static inline int qoa_clamp_s16(int v) { ++static int qoa_clamp_s16(int v) { + if ((unsigned int)(v + 32768) > 65535) { + if (v < -32768) { return -32768; } + if (v > 32767) { return 32767; } +@@ -316,7 +316,7 @@ static inline int qoa_clamp_s16(int v) { + return v; + } + +-static inline qoa_uint64_t qoa_read_u64(const unsigned char *bytes, unsigned int *p) { ++static qoa_uint64_t qoa_read_u64(const unsigned char *bytes, unsigned int *p) { + bytes += *p; + *p += 8; + return +@@ -326,7 +326,7 @@ static inline qoa_uint64_t qoa_read_u64(const unsigned char *bytes, unsigned int + ((qoa_uint64_t)(bytes[6]) << 8) | ((qoa_uint64_t)(bytes[7]) << 0); + } + +-static inline void qoa_write_u64(qoa_uint64_t v, unsigned char *bytes, unsigned int *p) { ++static void qoa_write_u64(qoa_uint64_t v, unsigned char *bytes, unsigned int *p) { + bytes += *p; + *p += 8; + bytes[0] = (v >> 56) & 0xff; +@@ -343,13 +343,13 @@ static inline void qoa_write_u64(qoa_uint64_t v, unsigned char *bytes, unsigned + /* ----------------------------------------------------------------------------- + Encoder */ + +-unsigned int qoa_encode_header(qoa_desc *qoa, unsigned char *bytes) { ++static inline unsigned int qoa_encode_header(qoa_desc *qoa, unsigned char *bytes) { + unsigned int p = 0; + qoa_write_u64(((qoa_uint64_t)QOA_MAGIC << 32) | qoa->samples, bytes, &p); + return p; + } + +-unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned int frame_len, unsigned char *bytes) { ++static inline unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned int frame_len, unsigned char *bytes) { + unsigned int channels = qoa->channels; + + unsigned int p = 0; +@@ -366,7 +366,7 @@ unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned + ), bytes, &p); + + +- for (int c = 0; c < channels; c++) { ++ for (unsigned int c = 0; c < channels; c++) { + /* Write the current LMS state */ + qoa_uint64_t weights = 0; + qoa_uint64_t history = 0; +@@ -380,9 +380,9 @@ unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned + + /* We encode all samples with the channels interleaved on a slice level. + E.g. for stereo: (ch-0, slice 0), (ch 1, slice 0), (ch 0, slice 1), ...*/ +- for (int sample_index = 0; sample_index < frame_len; sample_index += QOA_SLICE_LEN) { ++ for (unsigned int sample_index = 0; sample_index < frame_len; sample_index += QOA_SLICE_LEN) { + +- for (int c = 0; c < channels; c++) { ++ for (unsigned int c = 0; c < channels; c++) { + int slice_len = qoa_clamp(QOA_SLICE_LEN, 0, frame_len - sample_index); + int slice_start = sample_index * channels + c; + int slice_end = (sample_index + slice_len) * channels + c; +@@ -391,10 +391,10 @@ unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned + 16 scalefactors, encode all samples for the current slice and + meassure the total squared error. */ + qoa_uint64_t best_rank = -1; +- qoa_uint64_t best_error = -1; +- qoa_uint64_t best_slice; +- qoa_lms_t best_lms; +- int best_scalefactor; ++ //qoa_uint64_t best_error = -1; ++ qoa_uint64_t best_slice = -1; ++ qoa_lms_t best_lms = {{-1, -1, -1, -1}, {-1, -1, -1, -1}}; ++ int best_scalefactor = -1; + + for (int sfi = 0; sfi < 16; sfi++) { + /* There is a strong correlation between the scalefactors of +@@ -408,7 +408,7 @@ unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned + qoa_lms_t lms = qoa->lms[c]; + qoa_uint64_t slice = scalefactor; + qoa_uint64_t current_rank = 0; +- qoa_uint64_t current_error = 0; ++ //qoa_uint64_t current_error = 0; + + for (int si = slice_start; si < slice_end; si += channels) { + int sample = sample_data[si]; +@@ -438,7 +438,7 @@ unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned + qoa_uint64_t error_sq = error * error; + + current_rank += error_sq + weights_penalty * weights_penalty; +- current_error += error_sq; ++ //current_error += error_sq; + if (current_rank > best_rank) { + break; + } +@@ -449,7 +449,7 @@ unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned + + if (current_rank < best_rank) { + best_rank = current_rank; +- best_error = current_error; ++ //best_error = current_error; + best_slice = slice; + best_lms = lms; + best_scalefactor = scalefactor; +@@ -475,7 +475,7 @@ unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned + return p; + } + +-void *qoa_encode(const short *sample_data, qoa_desc *qoa, unsigned int *out_len) { ++inline void *qoa_encode(const short *sample_data, qoa_desc *qoa, unsigned int *out_len) { + if ( + qoa->samples == 0 || + qoa->samplerate == 0 || qoa->samplerate > 0xffffff || +@@ -492,9 +492,9 @@ void *qoa_encode(const short *sample_data, qoa_desc *qoa, unsigned int *out_len) + num_frames * QOA_LMS_LEN * 4 * qoa->channels + /* 4 * 4 bytes lms state per channel */ + num_slices * 8 * qoa->channels; /* 8 byte slices */ + +- unsigned char *bytes = QOA_MALLOC(encoded_size); ++ unsigned char *bytes = (unsigned char *)QOA_MALLOC(encoded_size); + +- for (int c = 0; c < qoa->channels; c++) { ++ for (unsigned int c = 0; c < qoa->channels; c++) { + /* Set the initial LMS weights to {0, 0, -1, 2}. This helps with the + prediction of the first few ms of a file. */ + qoa->lms[c].weights[0] = 0; +@@ -517,7 +517,7 @@ void *qoa_encode(const short *sample_data, qoa_desc *qoa, unsigned int *out_len) + #endif + + int frame_len = QOA_FRAME_LEN; +- for (int sample_index = 0; sample_index < qoa->samples; sample_index += frame_len) { ++ for (unsigned int sample_index = 0; sample_index < qoa->samples; sample_index += frame_len) { + frame_len = qoa_clamp(QOA_FRAME_LEN, 0, qoa->samples - sample_index); + const short *frame_samples = sample_data + sample_index * qoa->channels; + unsigned int frame_size = qoa_encode_frame(frame_samples, qoa, frame_len, bytes + p); +@@ -533,11 +533,11 @@ void *qoa_encode(const short *sample_data, qoa_desc *qoa, unsigned int *out_len) + /* ----------------------------------------------------------------------------- + Decoder */ + +-unsigned int qoa_max_frame_size(qoa_desc *qoa) { ++inline unsigned int qoa_max_frame_size(qoa_desc *qoa) { + return QOA_FRAME_SIZE(qoa->channels, QOA_SLICES_PER_FRAME); + } + +-unsigned int qoa_decode_header(const unsigned char *bytes, int size, qoa_desc *qoa) { ++static unsigned int qoa_decode_header(const unsigned char *bytes, int size, qoa_desc *qoa) { + unsigned int p = 0; + if (size < QOA_MIN_FILESIZE) { + return 0; +@@ -570,7 +570,7 @@ unsigned int qoa_decode_header(const unsigned char *bytes, int size, qoa_desc *q + return 8; + } + +-unsigned int qoa_decode_frame(const unsigned char *bytes, unsigned int size, qoa_desc *qoa, short *sample_data, unsigned int *frame_len) { ++inline unsigned int qoa_decode_frame(const unsigned char *bytes, unsigned int size, qoa_desc *qoa, short *sample_data, unsigned int *frame_len) { + unsigned int p = 0; + *frame_len = 0; + +@@ -580,14 +580,14 @@ unsigned int qoa_decode_frame(const unsigned char *bytes, unsigned int size, qoa + + /* Read and verify the frame header */ + qoa_uint64_t frame_header = qoa_read_u64(bytes, &p); +- int channels = (frame_header >> 56) & 0x0000ff; +- int samplerate = (frame_header >> 32) & 0xffffff; +- int samples = (frame_header >> 16) & 0x00ffff; +- int frame_size = (frame_header ) & 0x00ffff; ++ unsigned int channels = (frame_header >> 56) & 0x0000ff; ++ unsigned int samplerate = (frame_header >> 32) & 0xffffff; ++ unsigned int samples = (frame_header >> 16) & 0x00ffff; ++ unsigned int frame_size = (frame_header ) & 0x00ffff; + + int data_size = frame_size - 8 - QOA_LMS_LEN * 4 * channels; + int num_slices = data_size / 8; +- int max_total_samples = num_slices * QOA_SLICE_LEN; ++ unsigned int max_total_samples = num_slices * QOA_SLICE_LEN; + + if ( + channels != qoa->channels || +@@ -600,7 +600,7 @@ unsigned int qoa_decode_frame(const unsigned char *bytes, unsigned int size, qoa + + + /* Read the LMS state: 4 x 2 bytes history, 4 x 2 bytes weights per channel */ +- for (int c = 0; c < channels; c++) { ++ for (unsigned int c = 0; c < channels; c++) { + qoa_uint64_t history = qoa_read_u64(bytes, &p); + qoa_uint64_t weights = qoa_read_u64(bytes, &p); + for (int i = 0; i < QOA_LMS_LEN; i++) { +@@ -613,8 +613,8 @@ unsigned int qoa_decode_frame(const unsigned char *bytes, unsigned int size, qoa + + + /* Decode all slices for all channels in this frame */ +- for (int sample_index = 0; sample_index < samples; sample_index += QOA_SLICE_LEN) { +- for (int c = 0; c < channels; c++) { ++ for (unsigned int sample_index = 0; sample_index < samples; sample_index += QOA_SLICE_LEN) { ++ for (unsigned int c = 0; c < channels; c++) { + qoa_uint64_t slice = qoa_read_u64(bytes, &p); + + int scalefactor = (slice >> 60) & 0xf; +@@ -639,32 +639,32 @@ unsigned int qoa_decode_frame(const unsigned char *bytes, unsigned int size, qoa + return p; + } + +-short *qoa_decode(const unsigned char *bytes, int size, qoa_desc *qoa) { +- unsigned int p = qoa_decode_header(bytes, size, qoa); +- if (!p) { +- return NULL; +- } ++// short *qoa_decode(const unsigned char *bytes, int size, qoa_desc *qoa) { ++// unsigned int p = qoa_decode_header(bytes, size, qoa); ++// if (!p) { ++// return NULL; ++// } + +- /* Calculate the required size of the sample buffer and allocate */ +- int total_samples = qoa->samples * qoa->channels; +- short *sample_data = QOA_MALLOC(total_samples * sizeof(short)); ++// /* Calculate the required size of the sample buffer and allocate */ ++// int total_samples = qoa->samples * qoa->channels; ++// short *sample_data = (short *)QOA_MALLOC(total_samples * sizeof(short)); + +- unsigned int sample_index = 0; +- unsigned int frame_len; +- unsigned int frame_size; ++// unsigned int sample_index = 0; ++// unsigned int frame_len; ++// unsigned int frame_size; + +- /* Decode all frames */ +- do { +- short *sample_ptr = sample_data + sample_index * qoa->channels; +- frame_size = qoa_decode_frame(bytes + p, size - p, qoa, sample_ptr, &frame_len); ++// /* Decode all frames */ ++// do { ++// short *sample_ptr = sample_data + sample_index * qoa->channels; ++// frame_size = qoa_decode_frame(bytes + p, size - p, qoa, sample_ptr, &frame_len); + +- p += frame_size; +- sample_index += frame_len; +- } while (frame_size && sample_index < qoa->samples); ++// p += frame_size; ++// sample_index += frame_len; ++// } while (frame_size && sample_index < qoa->samples); + +- qoa->samples = sample_index; +- return sample_data; +-} ++// qoa->samples = sample_index; ++// return sample_data; ++// } + + + diff --git a/thirdparty/misc/qoa.h b/thirdparty/misc/qoa.h new file mode 100644 index 000000000000..242e7d8c8142 --- /dev/null +++ b/thirdparty/misc/qoa.h @@ -0,0 +1,732 @@ +/* + +Copyright (c) 2023, Dominic Szablewski - https://phoboslab.org +SPDX-License-Identifier: MIT + +QOA - The "Quite OK Audio" format for fast, lossy audio compression + + +-- Data Format + +QOA encodes pulse-code modulated (PCM) audio data with up to 255 channels, +sample rates from 1 up to 16777215 hertz and a bit depth of 16 bits. + +The compression method employed in QOA is lossy; it discards some information +from the uncompressed PCM data. For many types of audio signals this compression +is "transparent", i.e. the difference from the original file is often not +audible. + +QOA encodes 20 samples of 16 bit PCM data into slices of 64 bits. A single +sample therefore requires 3.2 bits of storage space, resulting in a 5x +compression (16 / 3.2). + +A QOA file consists of an 8 byte file header, followed by a number of frames. +Each frame contains an 8 byte frame header, the current 16 byte en-/decoder +state per channel and 256 slices per channel. Each slice is 8 bytes wide and +encodes 20 samples of audio data. + +All values, including the slices, are big endian. The file layout is as follows: + +struct { + struct { + char magic[4]; // magic bytes "qoaf" + uint32_t samples; // samples per channel in this file + } file_header; + + struct { + struct { + uint8_t num_channels; // no. of channels + uint24_t samplerate; // samplerate in hz + uint16_t fsamples; // samples per channel in this frame + uint16_t fsize; // frame size (includes this header) + } frame_header; + + struct { + int16_t history[4]; // most recent last + int16_t weights[4]; // most recent last + } lms_state[num_channels]; + + qoa_slice_t slices[256][num_channels]; + + } frames[ceil(samples / (256 * 20))]; +} qoa_file_t; + +Each `qoa_slice_t` contains a quantized scalefactor `sf_quant` and 20 quantized +residuals `qrNN`: + +.- QOA_SLICE -- 64 bits, 20 samples --------------------------/ /------------. +| Byte[0] | Byte[1] | Byte[2] \ \ Byte[7] | +| 7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0 | 7 6 5 / / 2 1 0 | +|------------+--------+--------+--------+---------+---------+-\ \--+---------| +| sf_quant | qr00 | qr01 | qr02 | qr03 | qr04 | / / | qr19 | +`-------------------------------------------------------------\ \------------` + +Each frame except the last must contain exactly 256 slices per channel. The last +frame may contain between 1 .. 256 (inclusive) slices per channel. The last +slice (for each channel) in the last frame may contain less than 20 samples; the +slice still must be 8 bytes wide, with the unused samples zeroed out. + +Channels are interleaved per slice. E.g. for 2 channel stereo: +slice[0] = L, slice[1] = R, slice[2] = L, slice[3] = R ... + +A valid QOA file or stream must have at least one frame. Each frame must contain +at least one channel and one sample with a samplerate between 1 .. 16777215 +(inclusive). + +If the total number of samples is not known by the encoder, the samples in the +file header may be set to 0x00000000 to indicate that the encoder is +"streaming". In a streaming context, the samplerate and number of channels may +differ from frame to frame. For static files (those with samples set to a +non-zero value), each frame must have the same number of channels and same +samplerate. + +Note that this implementation of QOA only handles files with a known total +number of samples. + +A decoder should support at least 8 channels. The channel layout for channel +counts 1 .. 8 is: + + 1. Mono + 2. L, R + 3. L, R, C + 4. FL, FR, B/SL, B/SR + 5. FL, FR, C, B/SL, B/SR + 6. FL, FR, C, LFE, B/SL, B/SR + 7. FL, FR, C, LFE, B, SL, SR + 8. FL, FR, C, LFE, BL, BR, SL, SR + +QOA predicts each audio sample based on the previously decoded ones using a +"Sign-Sign Least Mean Squares Filter" (LMS). This prediction plus the +dequantized residual forms the final output sample. + +*/ + + + +/* ----------------------------------------------------------------------------- + Header - Public functions */ + +#ifndef QOA_H +#define QOA_H + +#ifdef __cplusplus +extern "C" { +#endif + +#define QOA_MIN_FILESIZE 16 +#define QOA_MAX_CHANNELS 8 + +#define QOA_SLICE_LEN 20 +#define QOA_SLICES_PER_FRAME 256 +#define QOA_FRAME_LEN (QOA_SLICES_PER_FRAME * QOA_SLICE_LEN) +#define QOA_LMS_LEN 4 +#define QOA_MAGIC 0x716f6166 /* 'qoaf' */ + +#define QOA_FRAME_SIZE(channels, slices) \ + (8 + QOA_LMS_LEN * 4 * channels + 8 * slices * channels) + +typedef struct { + int history[QOA_LMS_LEN]; + int weights[QOA_LMS_LEN]; +} qoa_lms_t; + +typedef struct { + unsigned int channels; + unsigned int samplerate; + unsigned int samples; + qoa_lms_t lms[QOA_MAX_CHANNELS]; + #ifdef QOA_RECORD_TOTAL_ERROR + double error; + #endif +} qoa_desc; + +//unsigned int qoa_encode_header(qoa_desc *qoa, unsigned char *bytes); +//unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned int frame_len, unsigned char *bytes); +//void *qoa_encode(const short *sample_data, qoa_desc *qoa, unsigned int *out_len); + +//unsigned int qoa_max_frame_size(qoa_desc *qoa); +//unsigned int qoa_decode_header(const unsigned char *bytes, int size, qoa_desc *qoa); +//unsigned int qoa_decode_frame(const unsigned char *bytes, unsigned int size, qoa_desc *qoa, short *sample_data, unsigned int *frame_len); +//short *qoa_decode(const unsigned char *bytes, int size, qoa_desc *file); + +#ifndef QOA_NO_STDIO + +int qoa_write(const char *filename, const short *sample_data, qoa_desc *qoa); +void *qoa_read(const char *filename, qoa_desc *qoa); + +#endif /* QOA_NO_STDIO */ + + +#ifdef __cplusplus +} +#endif +#endif /* QOA_H */ + + +/* ----------------------------------------------------------------------------- + Implementation */ + +#ifdef QOA_IMPLEMENTATION +#include + +#ifndef QOA_MALLOC + #define QOA_MALLOC(sz) malloc(sz) + #define QOA_FREE(p) free(p) +#endif + +typedef unsigned long long qoa_uint64_t; + + +/* The quant_tab provides an index into the dequant_tab for residuals in the +range of -8 .. 8. It maps this range to just 3bits and becomes less accurate at +the higher end. Note that the residual zero is identical to the lowest positive +value. This is mostly fine, since the qoa_div() function always rounds away +from zero. */ + +static const int qoa_quant_tab[17] = { + 7, 7, 7, 5, 5, 3, 3, 1, /* -8..-1 */ + 0, /* 0 */ + 0, 2, 2, 4, 4, 6, 6, 6 /* 1.. 8 */ +}; + + +/* We have 16 different scalefactors. Like the quantized residuals these become +less accurate at the higher end. In theory, the highest scalefactor that we +would need to encode the highest 16bit residual is (2**16)/8 = 8192. However we +rely on the LMS filter to predict samples accurately enough that a maximum +residual of one quarter of the 16 bit range is sufficient. I.e. with the +scalefactor 2048 times the quant range of 8 we can encode residuals up to 2**14. + +The scalefactor values are computed as: +scalefactor_tab[s] <- round(pow(s + 1, 2.75)) */ + +static const int qoa_scalefactor_tab[16] = { + 1, 7, 21, 45, 84, 138, 211, 304, 421, 562, 731, 928, 1157, 1419, 1715, 2048 +}; + + +/* The reciprocal_tab maps each of the 16 scalefactors to their rounded +reciprocals 1/scalefactor. This allows us to calculate the scaled residuals in +the encoder with just one multiplication instead of an expensive division. We +do this in .16 fixed point with integers, instead of floats. + +The reciprocal_tab is computed as: +reciprocal_tab[s] <- ((1<<16) + scalefactor_tab[s] - 1) / scalefactor_tab[s] */ + +static const int qoa_reciprocal_tab[16] = { + 65536, 9363, 3121, 1457, 781, 475, 311, 216, 156, 117, 90, 71, 57, 47, 39, 32 +}; + + +/* The dequant_tab maps each of the scalefactors and quantized residuals to +their unscaled & dequantized version. + +Since qoa_div rounds away from the zero, the smallest entries are mapped to 3/4 +instead of 1. The dequant_tab assumes the following dequantized values for each +of the quant_tab indices and is computed as: +float dqt[8] = {0.75, -0.75, 2.5, -2.5, 4.5, -4.5, 7, -7}; +dequant_tab[s][q] <- round_ties_away_from_zero(scalefactor_tab[s] * dqt[q]) + +The rounding employed here is "to nearest, ties away from zero", i.e. positive +and negative values are treated symmetrically. +*/ + +static const int qoa_dequant_tab[16][8] = { + { 1, -1, 3, -3, 5, -5, 7, -7}, + { 5, -5, 18, -18, 32, -32, 49, -49}, + { 16, -16, 53, -53, 95, -95, 147, -147}, + { 34, -34, 113, -113, 203, -203, 315, -315}, + { 63, -63, 210, -210, 378, -378, 588, -588}, + { 104, -104, 345, -345, 621, -621, 966, -966}, + { 158, -158, 528, -528, 950, -950, 1477, -1477}, + { 228, -228, 760, -760, 1368, -1368, 2128, -2128}, + { 316, -316, 1053, -1053, 1895, -1895, 2947, -2947}, + { 422, -422, 1405, -1405, 2529, -2529, 3934, -3934}, + { 548, -548, 1828, -1828, 3290, -3290, 5117, -5117}, + { 696, -696, 2320, -2320, 4176, -4176, 6496, -6496}, + { 868, -868, 2893, -2893, 5207, -5207, 8099, -8099}, + {1064, -1064, 3548, -3548, 6386, -6386, 9933, -9933}, + {1286, -1286, 4288, -4288, 7718, -7718, 12005, -12005}, + {1536, -1536, 5120, -5120, 9216, -9216, 14336, -14336}, +}; + + +/* The Least Mean Squares Filter is the heart of QOA. It predicts the next +sample based on the previous 4 reconstructed samples. It does so by continuously +adjusting 4 weights based on the residual of the previous prediction. + +The next sample is predicted as the sum of (weight[i] * history[i]). + +The adjustment of the weights is done with a "Sign-Sign-LMS" that adds or +subtracts the residual to each weight, based on the corresponding sample from +the history. This, surprisingly, is sufficient to get worthwhile predictions. + +This is all done with fixed point integers. Hence the right-shifts when updating +the weights and calculating the prediction. */ + +static int qoa_lms_predict(qoa_lms_t *lms) { + int prediction = 0; + for (int i = 0; i < QOA_LMS_LEN; i++) { + prediction += lms->weights[i] * lms->history[i]; + } + return prediction >> 13; +} + +static void qoa_lms_update(qoa_lms_t *lms, int sample, int residual) { + int delta = residual >> 4; + for (int i = 0; i < QOA_LMS_LEN; i++) { + lms->weights[i] += lms->history[i] < 0 ? -delta : delta; + } + + for (int i = 0; i < QOA_LMS_LEN-1; i++) { + lms->history[i] = lms->history[i+1]; + } + lms->history[QOA_LMS_LEN-1] = sample; +} + + +/* qoa_div() implements a rounding division, but avoids rounding to zero for +small numbers. E.g. 0.1 will be rounded to 1. Note that 0 itself still +returns as 0, which is handled in the qoa_quant_tab[]. +qoa_div() takes an index into the .16 fixed point qoa_reciprocal_tab as an +argument, so it can do the division with a cheaper integer multiplication. */ + +static inline int qoa_div(int v, int scalefactor) { + int reciprocal = qoa_reciprocal_tab[scalefactor]; + int n = (v * reciprocal + (1 << 15)) >> 16; + n = n + ((v > 0) - (v < 0)) - ((n > 0) - (n < 0)); /* round away from 0 */ + return n; +} + +static int qoa_clamp(int v, int min, int max) { + if (v < min) { return min; } + if (v > max) { return max; } + return v; +} + +/* This specialized clamp function for the signed 16 bit range improves decode +performance quite a bit. The extra if() statement works nicely with the CPUs +branch prediction as this branch is rarely taken. */ + +static int qoa_clamp_s16(int v) { + if ((unsigned int)(v + 32768) > 65535) { + if (v < -32768) { return -32768; } + if (v > 32767) { return 32767; } + } + return v; +} + +static qoa_uint64_t qoa_read_u64(const unsigned char *bytes, unsigned int *p) { + bytes += *p; + *p += 8; + return + ((qoa_uint64_t)(bytes[0]) << 56) | ((qoa_uint64_t)(bytes[1]) << 48) | + ((qoa_uint64_t)(bytes[2]) << 40) | ((qoa_uint64_t)(bytes[3]) << 32) | + ((qoa_uint64_t)(bytes[4]) << 24) | ((qoa_uint64_t)(bytes[5]) << 16) | + ((qoa_uint64_t)(bytes[6]) << 8) | ((qoa_uint64_t)(bytes[7]) << 0); +} + +static void qoa_write_u64(qoa_uint64_t v, unsigned char *bytes, unsigned int *p) { + bytes += *p; + *p += 8; + bytes[0] = (v >> 56) & 0xff; + bytes[1] = (v >> 48) & 0xff; + bytes[2] = (v >> 40) & 0xff; + bytes[3] = (v >> 32) & 0xff; + bytes[4] = (v >> 24) & 0xff; + bytes[5] = (v >> 16) & 0xff; + bytes[6] = (v >> 8) & 0xff; + bytes[7] = (v >> 0) & 0xff; +} + + +/* ----------------------------------------------------------------------------- + Encoder */ + +static inline unsigned int qoa_encode_header(qoa_desc *qoa, unsigned char *bytes) { + unsigned int p = 0; + qoa_write_u64(((qoa_uint64_t)QOA_MAGIC << 32) | qoa->samples, bytes, &p); + return p; +} + +static inline unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned int frame_len, unsigned char *bytes) { + unsigned int channels = qoa->channels; + + unsigned int p = 0; + unsigned int slices = (frame_len + QOA_SLICE_LEN - 1) / QOA_SLICE_LEN; + unsigned int frame_size = QOA_FRAME_SIZE(channels, slices); + int prev_scalefactor[QOA_MAX_CHANNELS] = {0}; + + /* Write the frame header */ + qoa_write_u64(( + (qoa_uint64_t)qoa->channels << 56 | + (qoa_uint64_t)qoa->samplerate << 32 | + (qoa_uint64_t)frame_len << 16 | + (qoa_uint64_t)frame_size + ), bytes, &p); + + + for (unsigned int c = 0; c < channels; c++) { + /* Write the current LMS state */ + qoa_uint64_t weights = 0; + qoa_uint64_t history = 0; + for (int i = 0; i < QOA_LMS_LEN; i++) { + history = (history << 16) | (qoa->lms[c].history[i] & 0xffff); + weights = (weights << 16) | (qoa->lms[c].weights[i] & 0xffff); + } + qoa_write_u64(history, bytes, &p); + qoa_write_u64(weights, bytes, &p); + } + + /* We encode all samples with the channels interleaved on a slice level. + E.g. for stereo: (ch-0, slice 0), (ch 1, slice 0), (ch 0, slice 1), ...*/ + for (unsigned int sample_index = 0; sample_index < frame_len; sample_index += QOA_SLICE_LEN) { + + for (unsigned int c = 0; c < channels; c++) { + int slice_len = qoa_clamp(QOA_SLICE_LEN, 0, frame_len - sample_index); + int slice_start = sample_index * channels + c; + int slice_end = (sample_index + slice_len) * channels + c; + + /* Brute for search for the best scalefactor. Just go through all + 16 scalefactors, encode all samples for the current slice and + meassure the total squared error. */ + qoa_uint64_t best_rank = -1; + //qoa_uint64_t best_error = -1; + qoa_uint64_t best_slice = -1; + qoa_lms_t best_lms = {{-1, -1, -1, -1}, {-1, -1, -1, -1}}; + int best_scalefactor = -1; + + for (int sfi = 0; sfi < 16; sfi++) { + /* There is a strong correlation between the scalefactors of + neighboring slices. As an optimization, start testing + the best scalefactor of the previous slice first. */ + int scalefactor = (sfi + prev_scalefactor[c]) % 16; + + /* We have to reset the LMS state to the last known good one + before trying each scalefactor, as each pass updates the LMS + state when encoding. */ + qoa_lms_t lms = qoa->lms[c]; + qoa_uint64_t slice = scalefactor; + qoa_uint64_t current_rank = 0; + //qoa_uint64_t current_error = 0; + + for (int si = slice_start; si < slice_end; si += channels) { + int sample = sample_data[si]; + int predicted = qoa_lms_predict(&lms); + + int residual = sample - predicted; + int scaled = qoa_div(residual, scalefactor); + int clamped = qoa_clamp(scaled, -8, 8); + int quantized = qoa_quant_tab[clamped + 8]; + int dequantized = qoa_dequant_tab[scalefactor][quantized]; + int reconstructed = qoa_clamp_s16(predicted + dequantized); + + + /* If the weights have grown too large, we introduce a penalty + here. This prevents pops/clicks in certain problem cases */ + int weights_penalty = (( + lms.weights[0] * lms.weights[0] + + lms.weights[1] * lms.weights[1] + + lms.weights[2] * lms.weights[2] + + lms.weights[3] * lms.weights[3] + ) >> 18) - 0x8ff; + if (weights_penalty < 0) { + weights_penalty = 0; + } + + long long error = (sample - reconstructed); + qoa_uint64_t error_sq = error * error; + + current_rank += error_sq + weights_penalty * weights_penalty; + //current_error += error_sq; + if (current_rank > best_rank) { + break; + } + + qoa_lms_update(&lms, reconstructed, dequantized); + slice = (slice << 3) | quantized; + } + + if (current_rank < best_rank) { + best_rank = current_rank; + //best_error = current_error; + best_slice = slice; + best_lms = lms; + best_scalefactor = scalefactor; + } + } + + prev_scalefactor[c] = best_scalefactor; + + qoa->lms[c] = best_lms; + #ifdef QOA_RECORD_TOTAL_ERROR + qoa->error += best_error; + #endif + + /* If this slice was shorter than QOA_SLICE_LEN, we have to left- + shift all encoded data, to ensure the rightmost bits are the empty + ones. This should only happen in the last frame of a file as all + slices are completely filled otherwise. */ + best_slice <<= (QOA_SLICE_LEN - slice_len) * 3; + qoa_write_u64(best_slice, bytes, &p); + } + } + + return p; +} + +inline void *qoa_encode(const short *sample_data, qoa_desc *qoa, unsigned int *out_len) { + if ( + qoa->samples == 0 || + qoa->samplerate == 0 || qoa->samplerate > 0xffffff || + qoa->channels == 0 || qoa->channels > QOA_MAX_CHANNELS + ) { + return NULL; + } + + /* Calculate the encoded size and allocate */ + unsigned int num_frames = (qoa->samples + QOA_FRAME_LEN-1) / QOA_FRAME_LEN; + unsigned int num_slices = (qoa->samples + QOA_SLICE_LEN-1) / QOA_SLICE_LEN; + unsigned int encoded_size = 8 + /* 8 byte file header */ + num_frames * 8 + /* 8 byte frame headers */ + num_frames * QOA_LMS_LEN * 4 * qoa->channels + /* 4 * 4 bytes lms state per channel */ + num_slices * 8 * qoa->channels; /* 8 byte slices */ + + unsigned char *bytes = (unsigned char *)QOA_MALLOC(encoded_size); + + for (unsigned int c = 0; c < qoa->channels; c++) { + /* Set the initial LMS weights to {0, 0, -1, 2}. This helps with the + prediction of the first few ms of a file. */ + qoa->lms[c].weights[0] = 0; + qoa->lms[c].weights[1] = 0; + qoa->lms[c].weights[2] = -(1<<13); + qoa->lms[c].weights[3] = (1<<14); + + /* Explicitly set the history samples to 0, as we might have some + garbage in there. */ + for (int i = 0; i < QOA_LMS_LEN; i++) { + qoa->lms[c].history[i] = 0; + } + } + + + /* Encode the header and go through all frames */ + unsigned int p = qoa_encode_header(qoa, bytes); + #ifdef QOA_RECORD_TOTAL_ERROR + qoa->error = 0; + #endif + + int frame_len = QOA_FRAME_LEN; + for (unsigned int sample_index = 0; sample_index < qoa->samples; sample_index += frame_len) { + frame_len = qoa_clamp(QOA_FRAME_LEN, 0, qoa->samples - sample_index); + const short *frame_samples = sample_data + sample_index * qoa->channels; + unsigned int frame_size = qoa_encode_frame(frame_samples, qoa, frame_len, bytes + p); + p += frame_size; + } + + *out_len = p; + return bytes; +} + + + +/* ----------------------------------------------------------------------------- + Decoder */ + +inline unsigned int qoa_max_frame_size(qoa_desc *qoa) { + return QOA_FRAME_SIZE(qoa->channels, QOA_SLICES_PER_FRAME); +} + +static unsigned int qoa_decode_header(const unsigned char *bytes, int size, qoa_desc *qoa) { + unsigned int p = 0; + if (size < QOA_MIN_FILESIZE) { + return 0; + } + + + /* Read the file header, verify the magic number ('qoaf') and read the + total number of samples. */ + qoa_uint64_t file_header = qoa_read_u64(bytes, &p); + + if ((file_header >> 32) != QOA_MAGIC) { + return 0; + } + + qoa->samples = file_header & 0xffffffff; + if (!qoa->samples) { + return 0; + } + + /* Peek into the first frame header to get the number of channels and + the samplerate. */ + qoa_uint64_t frame_header = qoa_read_u64(bytes, &p); + qoa->channels = (frame_header >> 56) & 0x0000ff; + qoa->samplerate = (frame_header >> 32) & 0xffffff; + + if (qoa->channels == 0 || qoa->samples == 0 || qoa->samplerate == 0) { + return 0; + } + + return 8; +} + +inline unsigned int qoa_decode_frame(const unsigned char *bytes, unsigned int size, qoa_desc *qoa, short *sample_data, unsigned int *frame_len) { + unsigned int p = 0; + *frame_len = 0; + + if (size < 8 + QOA_LMS_LEN * 4 * qoa->channels) { + return 0; + } + + /* Read and verify the frame header */ + qoa_uint64_t frame_header = qoa_read_u64(bytes, &p); + unsigned int channels = (frame_header >> 56) & 0x0000ff; + unsigned int samplerate = (frame_header >> 32) & 0xffffff; + unsigned int samples = (frame_header >> 16) & 0x00ffff; + unsigned int frame_size = (frame_header ) & 0x00ffff; + + int data_size = frame_size - 8 - QOA_LMS_LEN * 4 * channels; + int num_slices = data_size / 8; + unsigned int max_total_samples = num_slices * QOA_SLICE_LEN; + + if ( + channels != qoa->channels || + samplerate != qoa->samplerate || + frame_size > size || + samples * channels > max_total_samples + ) { + return 0; + } + + + /* Read the LMS state: 4 x 2 bytes history, 4 x 2 bytes weights per channel */ + for (unsigned int c = 0; c < channels; c++) { + qoa_uint64_t history = qoa_read_u64(bytes, &p); + qoa_uint64_t weights = qoa_read_u64(bytes, &p); + for (int i = 0; i < QOA_LMS_LEN; i++) { + qoa->lms[c].history[i] = ((signed short)(history >> 48)); + history <<= 16; + qoa->lms[c].weights[i] = ((signed short)(weights >> 48)); + weights <<= 16; + } + } + + + /* Decode all slices for all channels in this frame */ + for (unsigned int sample_index = 0; sample_index < samples; sample_index += QOA_SLICE_LEN) { + for (unsigned int c = 0; c < channels; c++) { + qoa_uint64_t slice = qoa_read_u64(bytes, &p); + + int scalefactor = (slice >> 60) & 0xf; + int slice_start = sample_index * channels + c; + int slice_end = qoa_clamp(sample_index + QOA_SLICE_LEN, 0, samples) * channels + c; + + for (int si = slice_start; si < slice_end; si += channels) { + int predicted = qoa_lms_predict(&qoa->lms[c]); + int quantized = (slice >> 57) & 0x7; + int dequantized = qoa_dequant_tab[scalefactor][quantized]; + int reconstructed = qoa_clamp_s16(predicted + dequantized); + + sample_data[si] = reconstructed; + slice <<= 3; + + qoa_lms_update(&qoa->lms[c], reconstructed, dequantized); + } + } + } + + *frame_len = samples; + return p; +} + +// short *qoa_decode(const unsigned char *bytes, int size, qoa_desc *qoa) { +// unsigned int p = qoa_decode_header(bytes, size, qoa); +// if (!p) { +// return NULL; +// } + +// /* Calculate the required size of the sample buffer and allocate */ +// int total_samples = qoa->samples * qoa->channels; +// short *sample_data = (short *)QOA_MALLOC(total_samples * sizeof(short)); + +// unsigned int sample_index = 0; +// unsigned int frame_len; +// unsigned int frame_size; + +// /* Decode all frames */ +// do { +// short *sample_ptr = sample_data + sample_index * qoa->channels; +// frame_size = qoa_decode_frame(bytes + p, size - p, qoa, sample_ptr, &frame_len); + +// p += frame_size; +// sample_index += frame_len; +// } while (frame_size && sample_index < qoa->samples); + +// qoa->samples = sample_index; +// return sample_data; +// } + + + +/* ----------------------------------------------------------------------------- + File read/write convenience functions */ + +#ifndef QOA_NO_STDIO +#include + +int qoa_write(const char *filename, const short *sample_data, qoa_desc *qoa) { + FILE *f = fopen(filename, "wb"); + unsigned int size; + void *encoded; + + if (!f) { + return 0; + } + + encoded = qoa_encode(sample_data, qoa, &size); + if (!encoded) { + fclose(f); + return 0; + } + + fwrite(encoded, 1, size, f); + fclose(f); + + QOA_FREE(encoded); + return size; +} + +void *qoa_read(const char *filename, qoa_desc *qoa) { + FILE *f = fopen(filename, "rb"); + int size, bytes_read; + void *data; + short *sample_data; + + if (!f) { + return NULL; + } + + fseek(f, 0, SEEK_END); + size = ftell(f); + if (size <= 0) { + fclose(f); + return NULL; + } + fseek(f, 0, SEEK_SET); + + data = QOA_MALLOC(size); + if (!data) { + fclose(f); + return NULL; + } + + bytes_read = fread(data, 1, size, f); + fclose(f); + + sample_data = qoa_decode(data, bytes_read, qoa); + QOA_FREE(data); + return sample_data; +} + +#endif /* QOA_NO_STDIO */ +#endif /* QOA_IMPLEMENTATION */