feat: Implement QOA Encoder

[rafaelcaricio]

This commit introduces a functional encoder for the Quite OK Audio (QOA) format. The encoder is capable of taking raw PCM audio data (i16 samples), and producing a QOA compliant byte stream.

Key changes and implemented components:

1. Core Structures:

   • QoaEncoder<W: io::Write>: Manages the overall encoding process,
     state, and output writer.
   • EncodeError: Enum for encoder-specific errors.
   • QoaLms: The Least Mean Squares filter state struct was made public,
     along with its predict and update methods, to be shared with
     the encoder logic.

2. Quantization Logic:

   • find_closest_dequantized_value_in_row(): Helper to find the best
     quantized entry in a QOA_DEQUANT_TAB row, respecting tie-breaking.
   • quantize_residual(): Determines the 3-bit quantized value for a
     given residual and scale factor.
   • find_best_scale_factor_quantized_and_dequantized(): Finds the
     optimal scale factor and 3-bit quantized value for a given
     residual, minimizing error and respecting tie-breaking for scale
     factors.

3. Slice Encoding (encode_slice):

   • Encodes 20 audio samples for a single channel into a u64 slice.
   • Determines an optimal slice_scale_factor for the 20 samples.
   • Processes each sample: predicts, calculates residual, quantizes,
     dequantizes, reconstructs, and updates the LMS state.
   • Packs the 4-bit scale factor and 20 3-bit quantized values into the u64.

4. Frame Encoding (encode_frame):

   • Assembles a complete QOA frame.
   • Validates input parameters (channel count, sample rate, sample counts).
   • Calculates and validates the total frame_size to ensure it fits u16.
   • Writes the 8-byte frame header.
   • Writes the initial LMS state (history and weights as i16s) for each channel.
   • Encodes all slices for all channels (interleaved) by calling encode_slice
     and appends their u64 data.

5. Public API (QoaEncoder methods):

   • new(): Initializes the encoder, writes the QOA file header (magic
     number, total samples per channel).
   • write_frame(): Takes a frame's worth of audio data, encodes it using
     encode_frame, and writes the bytes to the output. Updates running
     sample counts.
   • finish(): Finalizes the encoding process, checks total sample counts
     against the header, and flushes the writer.

6. Big Endian Writing:

   • Standard Rust methods (.to_be_bytes() with write_all() or
     extend_from_slice()) are used for writing multi-byte integers in
     Big Endian format where required (file header, frame headers, LMS
     state, slice data).

7. Testing:

   • Unit tests for the quantization logic, including tie-breaking rules.
   • A round-trip integration test: generates sample audio, encodes it
     using the new QoaEncoder, decodes the output using the existing
     decode_all function, and compares the original and decoded samples
     with an error tolerance to account for QOA's lossy nature.

8. Constants:

   • The QOA_DEQUANT_TAB was confirmed to be public, allowing its use by
     the encoder. Other necessary constants like QOA_SLICE_LEN,
     QOA_LMS_LEN, QOA_MAGIC are also public.

The implementation follows the QOA specification for file and frame structure, LMS filter updates, and quantization.

[Copilot]

Copilot reviewed 1 out of 1 changed files in this pull request and generated no comments.

[Copilot]

Copilot reviewed 1 out of 1 changed files in this pull request and generated no comments.