Add support for QOA sound format by Ryu204 · Pull Request #3753 · SFML/SFML

Ryu204 · 2026-09-18T17:18:30Z

This PR adds support for QOA sound format. It was requested in #2969.

Since there is no dependency, some files containing common utilities for reader and writer were added (SoundFileQoa.hpp and SoundFileQoa.cpp).

Known limitations/remarks:

QOA only supports 32 bit sample count, while SFML interface support 64 bit.
QOA supports varying sample rate and a streaming mode which does not require sample count to be known. Both were not implemented.
Seeking relies on all frames having same sample rate and channel count.

Tasks

Tested on Linux
Tested on Windows

How to test this PR?

#include <SFML/Audio.hpp>
#include <chrono>
#include <filesystem>
#include <iostream>
#include <thread>

int main() {
  sf::SoundBuffer soundBuffer;
  if (!soundBuffer.loadFromFile(std::filesystem::path{"./coin.qoa"})) {
    std::cerr << "Failed to open sound file\n";
    return -1;
  }
  sf::Sound sound{soundBuffer};
  sound.play();
  std::this_thread::sleep_for(std::chrono::seconds{1});
  if (!soundBuffer.saveToFile(std::filesystem::path{"./coin2.qoa"})) {
    std::cerr << "Failed to saved new sound file\n";
    return -2;
  }
  return 0;
}

Bambo-Borris · 2026-10-01T13:17:39Z

+};
+
+template <typename Out, typename Num>
+constexpr Out clampInt(Num value)


Any reason not to use std::clamp? Quick search indicates std::clamp is used elsewhere in SFML.

Ignore me, I just re-read what this is doing

eXpl0it3r

Thanks for tackling this! 🙂

I went through the whole diff and I think, I found a few correctness issues in the writer, mostly in the encoding itself.

Instead of fixing those one by one, I believe it would make sense to vendor qoa.h similar to how we do it with QOI or STB in extlibs/headers. The reader and writer then only need to deal with the streams, the framing and the channel mapping.

Additionally, the lists of supported formats in the sf::SoundBuffer, sf::Music and sf::InputSoundFile documentation need to be updated.

eXpl0it3r · 2026-10-02T14:38:29Z

+    std::vector<std::uint8_t> buffer;
+    if (const auto error = seekAndWriteHeader(static_cast<std::uint32_t>(samplesPerChannel), buffer))
+    {
+        err() << "Failed to write QOA file header: " << *error << std::endl;
+        return;
+    }


write() can be called multiple times, sf::OutputSoundFile::write forwards every call as is. Here every call seeks back to 0, writes the header with only the sample count of that call, creates a fresh LMS state and writes the frames right after the header. If someone writes in chunks, only the last chunk survives.

The header should be written once in open() with a placeholder, the total sample count and the LMS state need to be members, incomplete frames need to be buffered, and the sample count gets patched when closing the file, similar to what the WAV writer does.

eXpl0it3r · 2026-10-02T14:39:50Z

+    for (std::size_t i = 0; i < channelCount; ++i)
+        m_remapTable[i] = static_cast<std::uint8_t>(
+            std::find(targetChannelMap.begin(), targetChannelMap.end(), channelMap[i]) - targetChannelMap.begin());
+


The remap table is the wrong way around. This stores the QOA position for input channel i, but in writeFrame it's used as "input index for output position i". Have a look at SoundFileWriterWav.cpp, there it's std::find(channelMap.begin(), channelMap.end(), targetChannelMap[i]).

Additionally, the slices of output channel k are encoded with lms.channels[m_remapTable[k]], while writeLmsState writes the states in index order. With any channel map that isn't the identity, the decoder ends up with the wrong predictor state from the second frame on.

eXpl0it3r · 2026-10-02T14:40:38Z

+    const auto frameBodySizeByte = qoaFile::getFrameSizeByte(m_frameSharedData->numChannels) -
+                                   qoaFile::frameHeaderSizeByte::value;


This always uses the size of a full frame with 256 slices, while the frame header declares the actual size. For the last frame, which is usually shorter, the whole buffer is written anyways, so the file ends with a bunch of zero bytes past the declared frame size. getFrameSizeByte(numChannels, slicesPerChannel) should be used here as well.

eXpl0it3r · 2026-10-02T14:44:50Z

+
+bool isChannelCountValid(std::uint8_t channelCount)
+{
+    return channelCount <= maxChannels;


This accepts 0 channels, which should fail like for other formats. In the writer count % numChannels then divides by zero, and on the reader side a crafted file gets through check() and open(), and ends up at sampleOffset / m_channelCount in seek().

eXpl0it3r · 2026-10-02T14:45:56Z

+    }
+
+    const auto sampleOffset = static_cast<std::uint32_t>(rawSampleOffset);
+    const auto isPastEnd    = sampleOffset / m_channelCount >= m_samplesPerChannel;


What's the plan for streaming files, i.e. samplesPerChannel == 0? The PR description says they're not supported, but open() succeeds with a sample count of 0 and read() does decode them. Here however every offset is considered past the end, so seek(0) jumps to EOF.

I'd either reject them in open() with a clear error message or support them properly. Have you checked other how other formats do it?

eXpl0it3r · 2026-10-02T20:40:27Z

+#include <SFML/Audio/SoundFileReaderQoa.hpp>
+
+#include <SFML/System/Err.hpp>
+#include <SFML/System/FileInputStream.hpp>


I think FileInputStream.hpp isn't used, while <algorithm> is missing for std::min and std::max.

eXpl0it3r · 2026-10-02T20:40:58Z

+    m_channelCount      = firstFrameHeader->numChannels;
+    m_sampleRate        = firstFrameHeader->sampleRate;
+    m_samplesPerChannel = headerContent->samplesPerChannel;
+    m_currentFrameSamples.clear();


m_decodedSamplesPerChannel isn't reset here, unlike the other members.

eXpl0it3r · 2026-10-02T20:41:21Z

+    if (remainingSamplesInFrame <= 0)
+        return 0;
+    const auto readSamplesCount = static_cast<std::uint16_t>(std::min<std::uint32_t>(remainingSamplesInFrame, maxCount));
+    std::memcpy(samples, m_currentFrameSamples.data() + m_currentFrameNextSampleIndex, readSamplesCount * 2);


sizeof(std::int16_t) instead of the magic 2, or just std::copy_n.

eXpl0it3r · 2026-10-02T20:41:43Z

+    std::vector<std::int16_t> m_currentFrameSamples; //!< Decoded samples of last processed frame
+    std::uint16_t m_currentFrameNextSampleIndex{};   //!< Index of next unread sample in the last processed frame
+    InputStream*  m_inputStream{};                   //!< The input stream received in the open method
+    std::size_t   m_streamFirstFramePosition{};


Missing documentation comment for m_streamFirstFramePosition.

eXpl0it3r · 2026-10-02T20:42:10Z

+    if (!std::is_permutation(channelMap.begin(), channelMap.end(), targetChannelMap.begin()))
+    {
+        err() << "Unsupported channel when writing QOA file" << std::endl;
+        return false;
+    }


With the three iterator overload this reads out of bounds, if channelMap.size() doesn't match channelCount. Use the overload that takes both end iterators.

Add support for QOA sound format

6d6cccf

Ryu204 force-pushed the feat/qoa-format branch from e40c122 to b51c06a Compare September 18, 2026 17:20

Ryu204 changed the title ~~Feat/qoa format~~ Add support for QOA sound format Sep 18, 2026

Ryu204 force-pushed the feat/qoa-format branch 2 times, most recently from 1ab7cdc to 6f00ef3 Compare September 22, 2026 15:15

Update tests for QOA sound format

4794aa5

Ryu204 force-pushed the feat/qoa-format branch from 6f00ef3 to 4794aa5 Compare September 22, 2026 15:43

Disable false positive auto* clang tidy check

7a26449

Ryu204 force-pushed the feat/qoa-format branch from 835e8f2 to 7a26449 Compare September 22, 2026 15:59

Bambo-Borris reviewed Oct 1, 2026

View reviewed changes

eXpl0it3r requested changes Oct 2, 2026

View reviewed changes

Navigation Menu

Uh oh!

Add support for QOA sound format - #3753

Add support for QOA sound format#3753
Ryu204 wants to merge 3 commits into
SFML:masterfrom
Ryu204:feat/qoa-format

Ryu204 commented Sep 18, 2026 •

edited

Loading

Uh oh!

Bambo-Borris Oct 1, 2026 •

edited

Loading

Uh oh!

eXpl0it3r left a comment

Uh oh!

eXpl0it3r Oct 2, 2026

Uh oh!

eXpl0it3r Oct 2, 2026

Uh oh!

eXpl0it3r Oct 2, 2026

Uh oh!

eXpl0it3r Oct 2, 2026

Uh oh!

eXpl0it3r Oct 2, 2026

Uh oh!

eXpl0it3r Oct 2, 2026

Uh oh!

eXpl0it3r Oct 2, 2026

Uh oh!

eXpl0it3r Oct 2, 2026

Uh oh!

eXpl0it3r Oct 2, 2026

Uh oh!

eXpl0it3r Oct 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		const auto frameBodySizeByte = qoaFile::getFrameSizeByte(m_frameSharedData->numChannels) -
		qoaFile::frameHeaderSizeByte::value;

Uh oh!

Conversation

Ryu204 commented Sep 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Tasks

How to test this PR?

Uh oh!

Bambo-Borris Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eXpl0it3r left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Ryu204 commented Sep 18, 2026 •

edited

Loading

Bambo-Borris Oct 1, 2026 •

edited

Loading