1
Fork 0
mirror of https://github.com/RGBCube/serenity synced 2025-07-28 02:17:34 +00:00

LibAudio: Rename Audio::Frame -> Audio::Sample

"Frame" is an MPEG term, which is not only unintuitive but also
overloaded with different meaning by other codecs (e.g. FLAC).
Therefore, use the standard term Sample for the central audio structure.

The class is also extracted to its own file, because it's becoming quite
large. Bundling these two changes means not distributing similar
modifications (changing names and paths) across commits.

Co-authored-by: kleines Filmröllchen <malu.bertsch@gmail.com>
This commit is contained in:
David Isaksson 2021-09-23 21:16:03 +02:00 committed by Brian Gianforcaro
parent fa4255bcf1
commit b6d075bb01
11 changed files with 179 additions and 165 deletions

View file

@ -45,7 +45,7 @@ i32 Buffer::allocate_id()
}
template<typename SampleReader>
static void read_samples_from_stream(InputMemoryStream& stream, SampleReader read_sample, Vector<Frame>& samples, int num_channels)
static void read_samples_from_stream(InputMemoryStream& stream, SampleReader read_sample, Vector<Sample>& samples, int num_channels)
{
double norm_l = 0;
double norm_r = 0;
@ -54,7 +54,7 @@ static void read_samples_from_stream(InputMemoryStream& stream, SampleReader rea
case 1:
for (;;) {
norm_l = read_sample(stream);
samples.append(Frame(norm_l));
samples.append(Sample(norm_l));
if (stream.handle_any_error()) {
break;
@ -65,7 +65,7 @@ static void read_samples_from_stream(InputMemoryStream& stream, SampleReader rea
for (;;) {
norm_l = read_sample(stream);
norm_r = read_sample(stream);
samples.append(Frame(norm_l, norm_r));
samples.append(Sample(norm_l, norm_r));
if (stream.handle_any_error()) {
break;
@ -130,7 +130,7 @@ RefPtr<Buffer> Buffer::from_pcm_data(ReadonlyBytes data, int num_channels, PcmSa
RefPtr<Buffer> Buffer::from_pcm_stream(InputMemoryStream& stream, int num_channels, PcmSampleFormat sample_format, int num_samples)
{
Vector<Frame> fdata;
Vector<Sample> fdata;
fdata.ensure_capacity(num_samples);
switch (sample_format) {
@ -189,7 +189,7 @@ template Vector<double> ResampleHelper<double>::resample(Vector<double>);
NonnullRefPtr<Buffer> resample_buffer(ResampleHelper<double>& resampler, Buffer const& to_resample)
{
Vector<Frame> resampled;
Vector<Sample> resampled;
resampled.ensure_capacity(to_resample.sample_count() * ceil_div(resampler.source(), resampler.target()));
for (size_t i = 0; i < static_cast<size_t>(to_resample.sample_count()); ++i) {
auto sample = to_resample.samples()[i];

View file

@ -8,144 +8,17 @@
#pragma once
#include <AK/ByteBuffer.h>
#include <AK/Math.h>
#include <AK/MemoryStream.h>
#include <AK/String.h>
#include <AK/Types.h>
#include <AK/Vector.h>
#include <LibAudio/Sample.h>
#include <LibCore/AnonymousBuffer.h>
#include <string.h>
namespace Audio {
using namespace AK::Exponentials;
// Constants for logarithmic volume. See Frame::operator*
// Corresponds to 60dB
constexpr double DYNAMIC_RANGE = 1000;
constexpr double VOLUME_A = 1 / DYNAMIC_RANGE;
double const VOLUME_B = log(DYNAMIC_RANGE);
// A single sample in an audio buffer.
// Values are floating point, and should range from -1.0 to +1.0
struct Frame {
constexpr Frame() = default;
// For mono
constexpr Frame(double left)
: left(left)
, right(left)
{
}
// For stereo
constexpr Frame(double left, double right)
: left(left)
, right(right)
{
}
void clip()
{
if (left > 1)
left = 1;
else if (left < -1)
left = -1;
if (right > 1)
right = 1;
else if (right < -1)
right = -1;
}
// Logarithmic scaling, as audio should ALWAYS do.
// Reference: https://www.dr-lex.be/info-stuff/volumecontrols.html
// We use the curve `factor = a * exp(b * change)`,
// where change is the input fraction we want to change by,
// a = 1/1000, b = ln(1000) = 6.908 and factor is the multiplier used.
// The value 1000 represents the dynamic range in sound pressure, which corresponds to 60 dB(A).
// This is a good dynamic range because it can represent all loudness values from
// 30 dB(A) (barely hearable with background noise)
// to 90 dB(A) (almost too loud to hear and about the reasonable limit of actual sound equipment).
//
// Format ranges:
// - Linear: 0.0 to 1.0
// - Logarithmic: 0.0 to 1.0
ALWAYS_INLINE double linear_to_log(double const change)
{
// TODO: Add linear slope around 0
return VOLUME_A * exp(VOLUME_B * change);
}
ALWAYS_INLINE double log_to_linear(double const val)
{
// TODO: Add linear slope around 0
return log(val / VOLUME_A) / VOLUME_B;
}
ALWAYS_INLINE Frame& log_multiply(double const change)
{
double factor = linear_to_log(change);
left *= factor;
right *= factor;
return *this;
}
ALWAYS_INLINE Frame log_multiplied(double const volume_change) const
{
Frame new_frame { left, right };
new_frame.log_multiply(volume_change);
return new_frame;
}
ALWAYS_INLINE Frame& log_pan(double const pan)
{
left *= linear_to_log(min(pan * -1 + 1.0, 1.0));
right *= linear_to_log(min(pan + 1.0, 1.0));
return *this;
}
ALWAYS_INLINE Frame log_pan(double const pan) const
{
Frame new_frame { left, right };
new_frame.log_pan(pan);
return new_frame;
}
constexpr Frame& operator*=(double const mult)
{
left *= mult;
right *= mult;
return *this;
}
constexpr Frame operator*(double const mult)
{
return { left * mult, right * mult };
}
constexpr Frame& operator+=(Frame const& other)
{
left += other.left;
right += other.right;
return *this;
}
constexpr Frame& operator+=(double other)
{
left += other;
right += other;
return *this;
}
constexpr Frame operator+(Frame const& other)
{
return { left + other.left, right + other.right };
}
double left { 0 };
double right { 0 };
};
// Supported PCM sample formats.
enum PcmSampleFormat : u8 {
Uint8,
@ -196,7 +69,7 @@ class Buffer : public RefCounted<Buffer> {
public:
static RefPtr<Buffer> from_pcm_data(ReadonlyBytes data, int num_channels, PcmSampleFormat sample_format);
static RefPtr<Buffer> from_pcm_stream(InputMemoryStream& stream, int num_channels, PcmSampleFormat sample_format, int num_samples);
static NonnullRefPtr<Buffer> create_with_samples(Vector<Frame>&& samples)
static NonnullRefPtr<Buffer> create_with_samples(Vector<Sample>&& samples)
{
return adopt_ref(*new Buffer(move(samples)));
}
@ -205,20 +78,20 @@ public:
return adopt_ref(*new Buffer(move(buffer), buffer_id, sample_count));
}
const Frame* samples() const { return (const Frame*)data(); }
const Sample* samples() const { return (const Sample*)data(); }
int sample_count() const { return m_sample_count; }
const void* data() const { return m_buffer.data<void>(); }
int size_in_bytes() const { return m_sample_count * (int)sizeof(Frame); }
int size_in_bytes() const { return m_sample_count * (int)sizeof(Sample); }
int id() const { return m_id; }
const Core::AnonymousBuffer& anonymous_buffer() const { return m_buffer; }
private:
explicit Buffer(const Vector<Frame> samples)
: m_buffer(Core::AnonymousBuffer::create_with_size(samples.size() * sizeof(Frame)).release_value())
explicit Buffer(const Vector<Sample> samples)
: m_buffer(Core::AnonymousBuffer::create_with_size(samples.size() * sizeof(Sample)).release_value())
, m_id(allocate_id())
, m_sample_count(samples.size())
{
memcpy(m_buffer.data<void>(), samples.data(), samples.size() * sizeof(Frame));
memcpy(m_buffer.data<void>(), samples.data(), samples.size() * sizeof(Sample));
}
explicit Buffer(Core::AnonymousBuffer buffer, i32 buffer_id, int sample_count)

View file

@ -231,7 +231,7 @@ void FlacLoaderPlugin::seek(const int position)
RefPtr<Buffer> FlacLoaderPlugin::get_more_samples(size_t max_bytes_to_read_from_input)
{
Vector<Frame> samples;
Vector<Sample> samples;
ssize_t remaining_samples = m_total_samples - m_loaded_samples;
if (remaining_samples <= 0) {
return nullptr;
@ -417,7 +417,7 @@ void FlacLoaderPlugin::next_frame()
m_current_frame_data.ensure_capacity(left.size());
// zip together channels
for (size_t i = 0; i < left.size(); ++i) {
Frame frame = { left[i] / sample_rescale, right[i] / sample_rescale };
Sample frame = { left[i] / sample_rescale, right[i] / sample_rescale };
m_current_frame_data.unchecked_append(frame);
}

View file

@ -143,7 +143,7 @@ private:
u64 m_data_start_location { 0 };
OwnPtr<FlacInputStream> m_stream;
Optional<FlacFrameHeader> m_current_frame;
Vector<Frame> m_current_frame_data;
Vector<Sample> m_current_frame_data;
u64 m_current_sample_or_frame { 0 };
};

View file

@ -0,0 +1,141 @@
/*
* Copyright (c) 2018-2020, Andreas Kling <kling@serenityos.org>
* Copyright (c) 2021, kleines Filmröllchen <malu.bertsch@gmail.com>
*
* SPDX-License-Identifier: BSD-2-Clause
*/
#pragma once
#include <AK/Math.h>
namespace Audio {
using namespace AK::Exponentials;
// Constants for logarithmic volume. See Sample::linear_to_log
// Corresponds to 60dB
constexpr double DYNAMIC_RANGE = 1000;
constexpr double VOLUME_A = 1 / DYNAMIC_RANGE;
double const VOLUME_B = log(DYNAMIC_RANGE);
// A single sample in an audio buffer.
// Values are floating point, and should range from -1.0 to +1.0
struct Sample {
constexpr Sample() = default;
// For mono
constexpr Sample(double left)
: left(left)
, right(left)
{
}
// For stereo
constexpr Sample(double left, double right)
: left(left)
, right(right)
{
}
void clip()
{
if (left > 1)
left = 1;
else if (left < -1)
left = -1;
if (right > 1)
right = 1;
else if (right < -1)
right = -1;
}
// Logarithmic scaling, as audio should ALWAYS do.
// Reference: https://www.dr-lex.be/info-stuff/volumecontrols.html
// We use the curve `factor = a * exp(b * change)`,
// where change is the input fraction we want to change by,
// a = 1/1000, b = ln(1000) = 6.908 and factor is the multiplier used.
// The value 1000 represents the dynamic range in sound pressure, which corresponds to 60 dB(A).
// This is a good dynamic range because it can represent all loudness values from
// 30 dB(A) (barely hearable with background noise)
// to 90 dB(A) (almost too loud to hear and about the reasonable limit of actual sound equipment).
//
// Format ranges:
// - Linear: 0.0 to 1.0
// - Logarithmic: 0.0 to 1.0
ALWAYS_INLINE double linear_to_log(double const change)
{
// TODO: Add linear slope around 0
return VOLUME_A * exp(VOLUME_B * change);
}
ALWAYS_INLINE double log_to_linear(double const val)
{
// TODO: Add linear slope around 0
return log(val / VOLUME_A) / VOLUME_B;
}
ALWAYS_INLINE Sample& log_multiply(double const change)
{
double factor = linear_to_log(change);
left *= factor;
right *= factor;
return *this;
}
ALWAYS_INLINE Sample log_multiplied(double const volume_change) const
{
Sample new_frame { left, right };
new_frame.log_multiply(volume_change);
return new_frame;
}
ALWAYS_INLINE Sample& log_pan(double const pan)
{
left *= linear_to_log(min(pan * -1 + 1.0, 1.0));
right *= linear_to_log(min(pan + 1.0, 1.0));
return *this;
}
ALWAYS_INLINE Sample log_pan(double const pan) const
{
Sample new_frame { left, right };
new_frame.log_pan(pan);
return new_frame;
}
constexpr Sample& operator*=(double const mult)
{
left *= mult;
right *= mult;
return *this;
}
constexpr Sample operator*(double const mult)
{
return { left * mult, right * mult };
}
constexpr Sample& operator+=(Sample const& other)
{
left += other.left;
right += other.right;
return *this;
}
constexpr Sample& operator+=(double other)
{
left += other;
right += other;
return *this;
}
constexpr Sample operator+(Sample const& other)
{
return { left + other.left, right + other.right };
}
double left { 0 };
double right { 0 };
};
}

View file

@ -14,7 +14,7 @@
namespace LibDSP {
// FIXME: Audio::Frame is 64-bit float, which is quite large for long clips.
using Sample = Audio::Frame;
using Sample = Audio::Sample;
Sample const SAMPLE_OFF = { 0.0, 0.0 };