1
Fork 0
mirror of https://github.com/RGBCube/serenity synced 2025-07-26 07:37:35 +00:00

LibAudio: New error propagation API in Loader and Buffer

Previously, a libc-like out-of-line error information was used in the
loader and its plugins. Now, all functions that may fail to do their job
return some sort of Result. The universally-used error type ist the new
LoaderError, which can contain information about the general error
category (such as file format, I/O, unimplemented features), an error
description, and location information, such as file index or sample
index.

Additionally, the loader plugins try to do as little work as possible in
their constructors. Right after being constructed, a user should call
initialize() and check the errors returned from there. (This is done
transparently by Loader itself.) If a constructor caused an error, the
call to initialize should check and return it immediately.

This opportunity was used to rework a lot of the internal error
propagation in both loader classes, especially FlacLoader. Therefore, a
couple of other refactorings may have sneaked in as well.

The adoption of LibAudio users is minimal. Piano's adoption is not
important, as the code will receive major refactoring in the near future
anyways. SoundPlayer's adoption is also less important, as changes to
refactor it are in the works as well. aplay's adoption is the best and
may serve as an example for other users. It also includes new buffering
behavior.

Buffer also gets some attention, making it OOM-safe and thereby also
propagating its errors to the user.
This commit is contained in:
kleines Filmröllchen 2021-11-27 17:00:19 +01:00 committed by Brian Gianforcaro
parent ec8bd8116d
commit 96d02a3e75
19 changed files with 406 additions and 397 deletions

View file

@ -10,6 +10,7 @@
#include <AK/Debug.h>
#include <AK/NumericLimits.h>
#include <AK/OwnPtr.h>
#include <AK/Try.h>
#include <LibCore/File.h>
#include <LibCore/FileStream.h>
@ -21,43 +22,43 @@ WavLoaderPlugin::WavLoaderPlugin(StringView path)
: m_file(Core::File::construct(path))
{
if (!m_file->open(Core::OpenMode::ReadOnly)) {
m_error_string = String::formatted("Can't open file: {}", m_file->error_string());
m_error = LoaderError { String::formatted("Can't open file: {}", m_file->error_string()) };
return;
}
m_stream = make<Core::InputFileStream>(*m_file);
}
valid = parse_header();
if (!valid)
return;
MaybeLoaderError WavLoaderPlugin::initialize()
{
if (m_error.has_value())
return m_error.release_value();
TRY(parse_header());
return {};
}
WavLoaderPlugin::WavLoaderPlugin(const ByteBuffer& buffer)
{
m_stream = make<InputMemoryStream>(buffer);
if (!m_stream) {
m_error_string = String::formatted("Can't open memory stream");
m_error = LoaderError { String::formatted("Can't open memory stream") };
return;
}
m_memory_stream = static_cast<InputMemoryStream*>(m_stream.ptr());
valid = parse_header();
if (!valid)
return;
}
RefPtr<Buffer> WavLoaderPlugin::get_more_samples(size_t max_bytes_to_read_from_input)
LoaderSamples WavLoaderPlugin::get_more_samples(size_t max_bytes_to_read_from_input)
{
if (!m_stream)
return nullptr;
return LoaderError { LoaderError::Category::Internal, static_cast<size_t>(m_loaded_samples), "No stream" };
int remaining_samples = m_total_samples - m_loaded_samples;
if (remaining_samples <= 0) {
return nullptr;
}
if (remaining_samples <= 0)
return Buffer::create_empty();
// One "sample" contains data from all channels.
// In the Wave spec, this is also called a block.
size_t bytes_per_sample = m_num_channels * pcm_bits_per_sample(m_sample_format) / 8;
size_t bytes_per_sample
= m_num_channels * pcm_bits_per_sample(m_sample_format) / 8;
// Might truncate if not evenly divisible by the sample size
int max_samples_to_read = static_cast<int>(max_bytes_to_read_from_input) / bytes_per_sample;
@ -71,28 +72,30 @@ RefPtr<Buffer> WavLoaderPlugin::get_more_samples(size_t max_bytes_to_read_from_i
auto sample_data_result = ByteBuffer::create_zeroed(bytes_to_read);
if (!sample_data_result.has_value())
return nullptr;
return LoaderError { LoaderError::Category::IO, static_cast<size_t>(m_loaded_samples), "Couldn't allocate sample buffer" };
auto sample_data = sample_data_result.release_value();
m_stream->read_or_error(sample_data.bytes());
if (m_stream->handle_any_error()) {
return nullptr;
}
if (m_stream->handle_any_error())
return LoaderError { LoaderError::Category::IO, static_cast<size_t>(m_loaded_samples), "Stream read error" };
RefPtr<Buffer> buffer = Buffer::from_pcm_data(
auto buffer = Buffer::from_pcm_data(
sample_data.bytes(),
m_num_channels,
m_sample_format);
if (buffer.is_error())
return LoaderError { LoaderError::Category::Internal, static_cast<size_t>(m_loaded_samples), "Couldn't allocate sample buffer" };
// m_loaded_samples should contain the amount of actually loaded samples
m_loaded_samples += samples_to_read;
return buffer;
return buffer.release_value();
}
void WavLoaderPlugin::seek(const int sample_index)
MaybeLoaderError WavLoaderPlugin::seek(const int sample_index)
{
dbgln_if(AWAVLOADER_DEBUG, "seek sample_index {}", sample_index);
if (sample_index < 0 || sample_index >= m_total_samples)
return;
return LoaderError { LoaderError::Category::Internal, static_cast<size_t>(m_loaded_samples), "Seek outside the sample range" };
size_t sample_offset = m_byte_offset_of_data_samples + (sample_index * m_num_channels * (pcm_bits_per_sample(m_sample_format) / 8));
@ -104,13 +107,14 @@ void WavLoaderPlugin::seek(const int sample_index)
}
m_loaded_samples = sample_index;
return {};
}
// Specification reference: http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/WAVE.html
bool WavLoaderPlugin::parse_header()
MaybeLoaderError WavLoaderPlugin::parse_header()
{
if (!m_stream)
return false;
return LoaderError { LoaderError::Category::Internal, 0, "No stream" };
bool ok = true;
size_t bytes_read = 0;
@ -142,77 +146,74 @@ bool WavLoaderPlugin::parse_header()
return value;
};
#define CHECK_OK(msg) \
do { \
if (!ok) { \
m_error_string = String::formatted("Parsing failed: {}", msg); \
dbgln_if(AWAVLOADER_DEBUG, m_error_string); \
return {}; \
} \
#define CHECK_OK(category, msg) \
do { \
if (!ok) \
return LoaderError { category, String::formatted("Parsing failed: {}", msg) }; \
} while (0)
u32 riff = read_u32();
ok = ok && riff == 0x46464952; // "RIFF"
CHECK_OK("RIFF header");
CHECK_OK(LoaderError::Category::Format, "RIFF header");
u32 sz = read_u32();
ok = ok && sz < maximum_wav_size;
CHECK_OK("File size");
CHECK_OK(LoaderError::Category::Format, "File size");
u32 wave = read_u32();
ok = ok && wave == 0x45564157; // "WAVE"
CHECK_OK("WAVE header");
CHECK_OK(LoaderError::Category::Format, "WAVE header");
u32 fmt_id = read_u32();
ok = ok && fmt_id == 0x20746D66; // "fmt "
CHECK_OK("FMT header");
CHECK_OK(LoaderError::Category::Format, "FMT header");
u32 fmt_size = read_u32();
ok = ok && (fmt_size == 16 || fmt_size == 18 || fmt_size == 40);
CHECK_OK("FMT size");
CHECK_OK(LoaderError::Category::Format, "FMT size");
u16 audio_format = read_u16();
CHECK_OK("Audio format"); // incomplete read check
CHECK_OK(LoaderError::Category::Format, "Audio format"); // incomplete read check
ok = ok && (audio_format == WAVE_FORMAT_PCM || audio_format == WAVE_FORMAT_IEEE_FLOAT || audio_format == WAVE_FORMAT_EXTENSIBLE);
CHECK_OK("Audio format PCM/Float"); // value check
CHECK_OK(LoaderError::Category::Unimplemented, "Audio format PCM/Float"); // value check
m_num_channels = read_u16();
ok = ok && (m_num_channels == 1 || m_num_channels == 2);
CHECK_OK("Channel count");
CHECK_OK(LoaderError::Category::Unimplemented, "Channel count");
m_sample_rate = read_u32();
CHECK_OK("Sample rate");
CHECK_OK(LoaderError::Category::IO, "Sample rate");
read_u32();
CHECK_OK("Data rate");
CHECK_OK(LoaderError::Category::IO, "Data rate");
u16 block_size_bytes = read_u16();
CHECK_OK("Block size");
CHECK_OK(LoaderError::Category::IO, "Block size");
u16 bits_per_sample = read_u16();
CHECK_OK("Bits per sample");
CHECK_OK(LoaderError::Category::IO, "Bits per sample");
if (audio_format == WAVE_FORMAT_EXTENSIBLE) {
ok = ok && (fmt_size == 40);
CHECK_OK("Extensible fmt size"); // value check
CHECK_OK(LoaderError::Category::Format, "Extensible fmt size"); // value check
// Discard everything until the GUID.
// We've already read 16 bytes from the stream. The GUID starts in another 8 bytes.
read_u32();
read_u32();
CHECK_OK("Discard until GUID");
CHECK_OK(LoaderError::Category::IO, "Discard until GUID");
// Get the underlying audio format from the first two bytes of GUID
u16 guid_subformat = read_u16();
ok = ok && (guid_subformat == WAVE_FORMAT_PCM || guid_subformat == WAVE_FORMAT_IEEE_FLOAT);
CHECK_OK("GUID SubFormat");
CHECK_OK(LoaderError::Category::Unimplemented, "GUID SubFormat");
audio_format = guid_subformat;
}
if (audio_format == WAVE_FORMAT_PCM) {
ok = ok && (bits_per_sample == 8 || bits_per_sample == 16 || bits_per_sample == 24);
CHECK_OK("Bits per sample (PCM)"); // value check
CHECK_OK(LoaderError::Category::Unimplemented, "Bits per sample (PCM)"); // value check
// We only support 8-24 bit audio right now because other formats are uncommon
if (bits_per_sample == 8) {
@ -224,7 +225,7 @@ bool WavLoaderPlugin::parse_header()
}
} else if (audio_format == WAVE_FORMAT_IEEE_FLOAT) {
ok = ok && (bits_per_sample == 32 || bits_per_sample == 64);
CHECK_OK("Bits per sample (Float)"); // value check
CHECK_OK(LoaderError::Category::Unimplemented, "Bits per sample (Float)"); // value check
// Again, only the common 32 and 64 bit
if (bits_per_sample == 32) {
@ -235,7 +236,7 @@ bool WavLoaderPlugin::parse_header()
}
ok = ok && (block_size_bytes == (m_num_channels * (bits_per_sample / 8)));
CHECK_OK("Block size sanity check");
CHECK_OK(LoaderError::Category::Format, "Block size sanity check");
dbgln_if(AWAVLOADER_DEBUG, "WAV format {} at {} bit, {} channels, rate {}Hz ",
sample_format_name(m_sample_format), pcm_bits_per_sample(m_sample_format), m_num_channels, m_sample_rate);
@ -246,17 +247,17 @@ bool WavLoaderPlugin::parse_header()
u8 search_byte = 0;
while (true) {
search_byte = read_u8();
CHECK_OK("Reading byte searching for data");
CHECK_OK(LoaderError::Category::IO, "Reading byte searching for data");
if (search_byte != 0x64) // D
continue;
search_byte = read_u8();
CHECK_OK("Reading next byte searching for data");
CHECK_OK(LoaderError::Category::IO, "Reading next byte searching for data");
if (search_byte != 0x61) // A
continue;
u16 search_remaining = read_u16();
CHECK_OK("Reading remaining bytes searching for data");
CHECK_OK(LoaderError::Category::IO, "Reading remaining bytes searching for data");
if (search_remaining != 0x6174) // TA
continue;
@ -266,10 +267,10 @@ bool WavLoaderPlugin::parse_header()
}
ok = ok && found_data;
CHECK_OK("Found no data chunk");
CHECK_OK(LoaderError::Category::Format, "Found no data chunk");
ok = ok && data_sz < maximum_wav_size;
CHECK_OK("Data was too large");
CHECK_OK(LoaderError::Category::Format, "Data was too large");
m_total_samples = data_sz / block_size_bytes;
@ -279,7 +280,6 @@ bool WavLoaderPlugin::parse_header()
m_total_samples);
m_byte_offset_of_data_samples = bytes_read;
return true;
return {};
}
}