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>

1 files changed, 7 insertions, 134 deletions

diff --git a/Userland/Libraries/LibAudio/Buffer.h b/Userland/Libraries/LibAudio/Buffer.h
index 6020a0f6a5..dbc08814e6 100644
--- a/Userland/Libraries/LibAudio/Buffer.h
+++ b/Userland/Libraries/LibAudio/Buffer.h
@@ -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)