/* Copyright (c) 2023, Dominic Szablewski - https://phoboslab.org SPDX-License-Identifier: MIT QOA - The "Quite OK Audio" format for fast, lossy audio compression -- Data Format QOA encodes pulse-code modulated (PCM) audio data with up to 255 channels, sample rates from 1 up to 16777215 hertz and a bit depth of 16 bits. The compression method employed in QOA is lossy; it discards some information from the uncompressed PCM data. For many types of audio signals this compression is "transparent", i.e. the difference from the original file is often not audible. QOA encodes 20 samples of 16 bit PCM data into slices of 64 bits. A single sample therefore requires 3.2 bits of storage space, resulting in a 5x compression (16 / 3.2). A QOA file consists of an 8 byte file header, followed by a number of frames. Each frame contains an 8 byte frame header, the current 16 byte en-/decoder state per channel and 256 slices per channel. Each slice is 8 bytes wide and encodes 20 samples of audio data. All values, including the slices, are big endian. The file layout is as follows: struct { struct { char magic[4]; // magic bytes "qoaf" uint32_t samples; // samples per channel in this file } file_header; struct { struct { uint8_t num_channels; // no. of channels uint24_t samplerate; // samplerate in hz uint16_t fsamples; // samples per channel in this frame uint16_t fsize; // frame size (includes this header) } frame_header; struct { int16_t history[4]; // most recent last int16_t weights[4]; // most recent last } lms_state[num_channels]; qoa_slice_t slices[256][num_channels]; } frames[ceil(samples / (256 * 20))]; } qoa_file_t; Each `qoa_slice_t` contains a quantized scalefactor `sf_quant` and 20 quantized residuals `qrNN`: .- QOA_SLICE -- 64 bits, 20 samples --------------------------/ /------------. | Byte[0] | Byte[1] | Byte[2] \ \ Byte[7] | | 7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0 | 7 6 5 / / 2 1 0 | |------------+--------+--------+--------+---------+---------+-\ \--+---------| | sf_quant | qr00 | qr01 | qr02 | qr03 | qr04 | / / | qr19 | `-------------------------------------------------------------\ \------------` Each frame except the last must contain exactly 256 slices per channel. The last frame may contain between 1 .. 256 (inclusive) slices per channel. The last slice (for each channel) in the last frame may contain less than 20 samples; the slice still must be 8 bytes wide, with the unused samples zeroed out. Channels are interleaved per slice. E.g. for 2 channel stereo: slice[0] = L, slice[1] = R, slice[2] = L, slice[3] = R ... A valid QOA file or stream must have at least one frame. Each frame must contain at least one channel and one sample with a samplerate between 1 .. 16777215 (inclusive). If the total number of samples is not known by the encoder, the samples in the file header may be set to 0x00000000 to indicate that the encoder is "streaming". In a streaming context, the samplerate and number of channels may differ from frame to frame. For static files (those with samples set to a non-zero value), each frame must have the same number of channels and same samplerate. Note that this implementation of QOA only handles files with a known total number of samples. A decoder should support at least 8 channels. The channel layout for channel counts 1 .. 8 is: 1. Mono 2. L, R 3. L, R, C 4. FL, FR, B/SL, B/SR 5. FL, FR, C, B/SL, B/SR 6. FL, FR, C, LFE, B/SL, B/SR 7. FL, FR, C, LFE, B, SL, SR 8. FL, FR, C, LFE, BL, BR, SL, SR QOA predicts each audio sample based on the previously decoded ones using a "Sign-Sign Least Mean Squares Filter" (LMS). This prediction plus the dequantized residual forms the final output sample. */ /* ----------------------------------------------------------------------------- Header - Public functions */ #ifndef QOA_H #define QOA_H #ifdef __cplusplus extern "C" { #endif #define QOA_MIN_FILESIZE … #define QOA_MAX_CHANNELS … #define QOA_SLICE_LEN … #define QOA_SLICES_PER_FRAME … #define QOA_FRAME_LEN … #define QOA_LMS_LEN … #define QOA_MAGIC … #define QOA_FRAME_SIZE(channels, slices) … qoa_lms_t; qoa_desc; inline unsigned int qoa_encode_header(qoa_desc *qoa, unsigned char *bytes); inline unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned int frame_len, unsigned char *bytes); inline void *qoa_encode(const short *sample_data, qoa_desc *qoa, unsigned int *out_len); inline unsigned int qoa_max_frame_size(qoa_desc *qoa); inline unsigned int qoa_decode_header(const unsigned char *bytes, int size, qoa_desc *qoa); inline unsigned int qoa_decode_frame(const unsigned char *bytes, unsigned int size, qoa_desc *qoa, short *sample_data, unsigned int *frame_len); inline short *qoa_decode(const unsigned char *bytes, int size, qoa_desc *file); #ifndef QOA_NO_STDIO int qoa_write(const char *filename, const short *sample_data, qoa_desc *qoa); void *qoa_read(const char *filename, qoa_desc *qoa); #endif /* QOA_NO_STDIO */ #ifdef __cplusplus } #endif #endif /* QOA_H */ /* ----------------------------------------------------------------------------- Implementation */ #ifdef QOA_IMPLEMENTATION #include <stdlib.h> #ifndef QOA_MALLOC #define QOA_MALLOC(sz) … #define QOA_FREE(p) … #endif qoa_uint64_t; /* The quant_tab provides an index into the dequant_tab for residuals in the range of -8 .. 8. It maps this range to just 3bits and becomes less accurate at the higher end. Note that the residual zero is identical to the lowest positive value. This is mostly fine, since the qoa_div() function always rounds away from zero. */ static const int qoa_quant_tab[17] = …; /* We have 16 different scalefactors. Like the quantized residuals these become less accurate at the higher end. In theory, the highest scalefactor that we would need to encode the highest 16bit residual is (2**16)/8 = 8192. However we rely on the LMS filter to predict samples accurately enough that a maximum residual of one quarter of the 16 bit range is sufficient. I.e. with the scalefactor 2048 times the quant range of 8 we can encode residuals up to 2**14. The scalefactor values are computed as: scalefactor_tab[s] <- round(pow(s + 1, 2.75)) */ static const int qoa_scalefactor_tab[16] = …; /* The reciprocal_tab maps each of the 16 scalefactors to their rounded reciprocals 1/scalefactor. This allows us to calculate the scaled residuals in the encoder with just one multiplication instead of an expensive division. We do this in .16 fixed point with integers, instead of floats. The reciprocal_tab is computed as: reciprocal_tab[s] <- ((1<<16) + scalefactor_tab[s] - 1) / scalefactor_tab[s] */ static const int qoa_reciprocal_tab[16] = …; /* The dequant_tab maps each of the scalefactors and quantized residuals to their unscaled & dequantized version. Since qoa_div rounds away from the zero, the smallest entries are mapped to 3/4 instead of 1. The dequant_tab assumes the following dequantized values for each of the quant_tab indices and is computed as: float dqt[8] = {0.75, -0.75, 2.5, -2.5, 4.5, -4.5, 7, -7}; dequant_tab[s][q] <- round_ties_away_from_zero(scalefactor_tab[s] * dqt[q]) The rounding employed here is "to nearest, ties away from zero", i.e. positive and negative values are treated symmetrically. */ static const int qoa_dequant_tab[16][8] = …; /* The Least Mean Squares Filter is the heart of QOA. It predicts the next sample based on the previous 4 reconstructed samples. It does so by continuously adjusting 4 weights based on the residual of the previous prediction. The next sample is predicted as the sum of (weight[i] * history[i]). The adjustment of the weights is done with a "Sign-Sign-LMS" that adds or subtracts the residual to each weight, based on the corresponding sample from the history. This, surprisingly, is sufficient to get worthwhile predictions. This is all done with fixed point integers. Hence the right-shifts when updating the weights and calculating the prediction. */ static int qoa_lms_predict(qoa_lms_t *lms) { … } static void qoa_lms_update(qoa_lms_t *lms, int sample, int residual) { … } /* qoa_div() implements a rounding division, but avoids rounding to zero for small numbers. E.g. 0.1 will be rounded to 1. Note that 0 itself still returns as 0, which is handled in the qoa_quant_tab[]. qoa_div() takes an index into the .16 fixed point qoa_reciprocal_tab as an argument, so it can do the division with a cheaper integer multiplication. */ static inline int qoa_div(int v, int scalefactor) { … } static inline int qoa_clamp(int v, int min, int max) { … } /* This specialized clamp function for the signed 16 bit range improves decode performance quite a bit. The extra if() statement works nicely with the CPUs branch prediction as this branch is rarely taken. */ static inline int qoa_clamp_s16(int v) { … } static inline qoa_uint64_t qoa_read_u64(const unsigned char *bytes, unsigned int *p) { … } static inline void qoa_write_u64(qoa_uint64_t v, unsigned char *bytes, unsigned int *p) { … } /* ----------------------------------------------------------------------------- Encoder */ unsigned int qoa_encode_header(qoa_desc *qoa, unsigned char *bytes) { … } unsigned int qoa_encode_frame(const short *sample_data, qoa_desc *qoa, unsigned int frame_len, unsigned char *bytes) { … } void *qoa_encode(const short *sample_data, qoa_desc *qoa, unsigned int *out_len) { … } /* ----------------------------------------------------------------------------- Decoder */ unsigned int qoa_max_frame_size(qoa_desc *qoa) { … } unsigned int qoa_decode_header(const unsigned char *bytes, int size, qoa_desc *qoa) { … } unsigned int qoa_decode_frame(const unsigned char *bytes, unsigned int size, qoa_desc *qoa, short *sample_data, unsigned int *frame_len) { … } short *qoa_decode(const unsigned char *bytes, int size, qoa_desc *qoa) { … } /* ----------------------------------------------------------------------------- File read/write convenience functions */ #ifndef QOA_NO_STDIO #include <stdio.h> int qoa_write(const char *filename, const short *sample_data, qoa_desc *qoa) { FILE *f = fopen(filename, "wb"); unsigned int size; void *encoded; if (!f) { return 0; } encoded = qoa_encode(sample_data, qoa, &size); if (!encoded) { fclose(f); return 0; } fwrite(encoded, 1, size, f); fclose(f); QOA_FREE(encoded); return size; } void *qoa_read(const char *filename, qoa_desc *qoa) { FILE *f = fopen(filename, "rb"); int size, bytes_read; void *data; short *sample_data; if (!f) { return NULL; } fseek(f, 0, SEEK_END); size = ftell(f); if (size <= 0) { fclose(f); return NULL; } fseek(f, 0, SEEK_SET); data = QOA_MALLOC(size); if (!data) { fclose(f); return NULL; } bytes_read = fread(data, 1, size, f); fclose(f); sample_data = qoa_decode(data, bytes_read, qoa); QOA_FREE(data); return sample_data; } #endif /* QOA_NO_STDIO */ #endif /* QOA_IMPLEMENTATION */
Codebase Browser
godot