Home /Modules/codecs/flac_native.c

flac_native.c

codecs/backends/flac_native/flac_native.c · 394 line(s) · c

/*
 * In-tree FLAC decode backend (dependency-free). See flac_native.h.
 *
 * Decodes the normative core of a FLAC stream to interleaved signed 16-bit PCM:
 * the STREAMINFO metadata block, then one or more audio frames, each carrying
 * CONSTANT / VERBATIM / FIXED subframes with Rice-coded residuals. The decoder
 * is bit-exact for the subframe types it covers and reports a clean
 * SLEELA_CODEC_ERR_UNSUPPORTED / _FORMAT for anything outside that coverage
 * rather than emitting wrong samples.
 *
 * References: the FLAC format specification (Xiph.Org). All structures below
 * (stream marker "fLaC", metadata block header, frame header with its UTF-8
 * coded sample/frame number, subframe header, Rice partitioned residual, and
 * the fixed predictor restoration filters) follow that normative description.
 */

#include "flac_native.h"

#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>

/* ----------------------------------------------------------------------------
 * Big-endian bit reader over a byte buffer.
 * -------------------------------------------------------------------------- */
typedef struct bitreader {
    const uint8_t *data;
    size_t         len;      /* total bytes                     */
    size_t         byte;     /* next byte index                 */
    unsigned       bit;      /* bits already consumed in data[byte] (0..7) */
    int            error;    /* set on read past end            */
} bitreader;

static void br_init(bitreader *b, const uint8_t *data, size_t len) {
    b->data = data; b->len = len; b->byte = 0; b->bit = 0; b->error = 0;
}

/* Read a single bit (MSB first). */
static unsigned br_bit(bitreader *b) {
    if (b->byte >= b->len) { b->error = 1; return 0; }
    unsigned v = (b->data[b->byte] >> (7u - b->bit)) & 1u;
    if (++b->bit == 8u) { b->bit = 0; b->byte++; }
    return v;
}

/* Read n bits (n <= 32) as an unsigned big-endian value. */
static uint32_t br_bits(bitreader *b, unsigned n) {
    uint32_t v = 0;
    for (unsigned i = 0; i < n; ++i) v = (v << 1) | br_bit(b);
    return v;
}

/* Read n bits as a two's-complement signed value (n in 1..32). */
static int32_t br_sbits(bitreader *b, unsigned n) {
    uint32_t v = br_bits(b, n);
    if (n == 0) return 0;
    if (v & (1u << (n - 1))) {                 /* sign-extend */
        uint32_t mask = (n >= 32) ? 0xFFFFFFFFu : ~((1u << n) - 1u);
        v |= mask;
    }
    return (int32_t)v;
}

/* Align to the next byte boundary. */
static void br_align(bitreader *b) {
    if (b->bit != 0) { b->bit = 0; b->byte++; }
}

/* Unary count of leading zeros terminated by a 1 bit (for Rice quotient). */
static uint32_t br_unary(bitreader *b) {
    uint32_t q = 0;
    while (!b->error && br_bit(b) == 0) q++;
    return q;
}

/* ----------------------------------------------------------------------------
 * Fixed predictor restoration (orders 0..4), FLAC's normative fixed filters.
 * The residual array is overwritten in place with the restored samples.
 * -------------------------------------------------------------------------- */
static void fixed_restore(int32_t *s, size_t n, unsigned order) {
    switch (order) {
        case 0:
            break;                                   /* residual == samples */
        case 1:
            for (size_t i = 1; i < n; ++i) s[i] += s[i - 1];
            break;
        case 2:
            for (size_t i = 2; i < n; ++i) s[i] += 2 * s[i - 1] - s[i - 2];
            break;
        case 3:
            for (size_t i = 3; i < n; ++i)
                s[i] += 3 * s[i - 1] - 3 * s[i - 2] + s[i - 3];
            break;
        case 4:
            for (size_t i = 4; i < n; ++i)
                s[i] += 4 * s[i - 1] - 6 * s[i - 2] + 4 * s[i - 3] - s[i - 4];
            break;
        default:
            break;
    }
}

/* ----------------------------------------------------------------------------
 * Rice-coded residual (coding methods 0 = 4-bit params, 1 = 5-bit params).
 * Fills residual[pred_order .. block_size) following FLAC partitioning.
 * Returns 0 on success, non-zero on an unsupported/escape case.
 * -------------------------------------------------------------------------- */
static int read_residual(bitreader *b, int32_t *out, unsigned block_size,
                         unsigned pred_order) {
    unsigned method = br_bits(b, 2);
    if (method > 1) return 1;                        /* reserved coding method */
    unsigned param_bits = (method == 0) ? 4u : 5u;
    unsigned escape     = (method == 0) ? 0x0Fu : 0x1Fu;

    unsigned partition_order = br_bits(b, 4);
    unsigned partitions = 1u << partition_order;
    if (block_size % partitions) return 1;           /* must divide evenly */
    unsigned per_part = block_size >> partition_order;
    if (per_part <= pred_order && partition_order == 0) {
        /* first partition must still have room for the warmup samples */
    }

    size_t idx = pred_order;
    for (unsigned p = 0; p < partitions; ++p) {
        unsigned count = (p == 0) ? (per_part - pred_order) : per_part;
        unsigned rice = br_bits(b, param_bits);
        if (rice == escape) {
            /* Escape: `n`-bit raw residuals, n given by the next 5 bits. */
            unsigned nbits = br_bits(b, 5);
            for (unsigned i = 0; i < count; ++i) {
                if (idx >= block_size) return 1;
                out[idx++] = nbits ? br_sbits(b, nbits) : 0;
            }
        } else {
            for (unsigned i = 0; i < count; ++i) {
                if (idx >= block_size) return 1;
                uint32_t q = br_unary(b);
                uint32_t r = br_bits(b, rice);
                uint32_t u = (q << rice) | r;         /* zig-zag folded value */
                int32_t v = (int32_t)(u >> 1);
                if (u & 1u) v = -v - 1;                /* unfold to signed */
                out[idx++] = v;
                if (b->error) return 1;
            }
        }
    }
    return b->error ? 1 : 0;
}

/* ----------------------------------------------------------------------------
 * One subframe for a single channel. `bps` is the effective bit depth for this
 * subframe (may be one more than STREAMINFO for a channel-decorrelated side).
 * Writes `block_size` samples into `out`. Returns 0 on success.
 * -------------------------------------------------------------------------- */
static int read_subframe(bitreader *b, int32_t *out, unsigned block_size,
                         unsigned bps) {
    if (br_bit(b) != 0) return 1;                    /* zero padding bit */
    unsigned type = br_bits(b, 6);

    unsigned wasted = 0;
    if (br_bit(b)) {                                  /* wasted-bits flag */
        wasted = 1 + br_unary(b);
    }
    if (wasted >= bps) return 1;
    unsigned ebps = bps - wasted;

    if (type == 0) {
        /* CONSTANT */
        int32_t v = br_sbits(b, ebps);
        for (unsigned i = 0; i < block_size; ++i) out[i] = v;
    } else if (type == 1) {
        /* VERBATIM */
        for (unsigned i = 0; i < block_size; ++i) out[i] = br_sbits(b, ebps);
    } else if (type >= 8 && type <= 12) {
        /* FIXED predictor, order = type - 8 (0..4). */
        unsigned order = type - 8;
        if (order > block_size) return 1;
        for (unsigned i = 0; i < order; ++i) out[i] = br_sbits(b, ebps); /* warmup */
        if (read_residual(b, out, block_size, order)) return 1;
        fixed_restore(out, block_size, order);
    } else if (type >= 32) {
        /* LPC (type 32..63): adaptive quantized linear prediction. Detected and
         * reported as unsupported rather than mis-decoded. */
        return 2;
    } else {
        return 1;                                     /* reserved subframe type */
    }

    if (wasted) for (unsigned i = 0; i < block_size; ++i) out[i] <<= wasted;
    return 0;
}

/* ----------------------------------------------------------------------------
 * Skip a frame header's UTF-8 coded sample/frame number (1..7 bytes).
 * -------------------------------------------------------------------------- */
static void skip_utf8_coded(bitreader *b, unsigned first) {
    unsigned extra = 0;
    if (first < 0x80u) extra = 0;
    else if ((first & 0xE0u) == 0xC0u) extra = 1;
    else if ((first & 0xF0u) == 0xE0u) extra = 2;
    else if ((first & 0xF8u) == 0xF0u) extra = 3;
    else if ((first & 0xFCu) == 0xF8u) extra = 4;
    else if ((first & 0xFEu) == 0xFCu) extra = 5;
    else extra = 6;
    for (unsigned i = 0; i < extra; ++i) (void)br_bits(b, 8);
}

/* STREAMINFO fields we need. */
typedef struct streaminfo {
    uint32_t sample_rate;
    uint16_t channels;
    uint16_t bits_per_sample;
    uint64_t total_samples;
} streaminfo;

/* ----------------------------------------------------------------------------
 * Decode a full FLAC stream to interleaved 16-bit PCM.
 * -------------------------------------------------------------------------- */
static sleela_codec_result flac_decode(const uint8_t *input, size_t input_len,
                                       sleela_pcm_buffer *out) {
    if (!input || !out) return SLEELA_CODEC_ERR_INVALID;
    if (input_len < 4 || memcmp(input, "fLaC", 4) != 0) return SLEELA_CODEC_ERR_FORMAT;

    bitreader b;
    br_init(&b, input, input_len);
    b.byte = 4;                                       /* past "fLaC" */

    /* --- Metadata blocks: find STREAMINFO (type 0), skip the rest. --- */
    streaminfo si; memset(&si, 0, sizeof(si));
    int have_streaminfo = 0;
    for (;;) {
        unsigned last = br_bit(&b);
        unsigned btype = br_bits(&b, 7);
        uint32_t blen = br_bits(&b, 24);
        if (b.error) return SLEELA_CODEC_ERR_FORMAT;
        if (btype == 0) {                             /* STREAMINFO */
            if (blen < 34) return SLEELA_CODEC_ERR_FORMAT;
            (void)br_bits(&b, 16);                    /* min block size */
            (void)br_bits(&b, 16);                    /* max block size */
            (void)br_bits(&b, 24);                    /* min frame size */
            (void)br_bits(&b, 24);                    /* max frame size */
            si.sample_rate     = br_bits(&b, 20);
            si.channels        = (uint16_t)(br_bits(&b, 3) + 1);
            si.bits_per_sample = (uint16_t)(br_bits(&b, 5) + 1);
            uint32_t hi = br_bits(&b, 4);
            uint32_t lo = br_bits(&b, 32);
            si.total_samples = ((uint64_t)hi << 32) | lo;
            for (unsigned i = 0; i < 16; ++i) (void)br_bits(&b, 8); /* MD5 */
            have_streaminfo = 1;
        } else {
            for (uint32_t i = 0; i < blen; ++i) (void)br_bits(&b, 8);
        }
        if (b.error) return SLEELA_CODEC_ERR_FORMAT;
        if (last) break;
    }
    if (!have_streaminfo) return SLEELA_CODEC_ERR_FORMAT;
    if (si.bits_per_sample != 16) return SLEELA_CODEC_ERR_UNSUPPORTED; /* 16-bit PCM boundary */
    if (si.channels < 1 || si.channels > 8) return SLEELA_CODEC_ERR_UNSUPPORTED;

    /* --- Audio frames. Accumulate interleaved 16-bit samples. --- */
    size_t cap = (si.total_samples ? (size_t)si.total_samples : 4096) * si.channels;
    if (cap == 0) cap = 4096;
    int16_t *pcm = (int16_t *)malloc(cap * sizeof(int16_t));
    if (!pcm) return SLEELA_CODEC_ERR_IO;
    size_t pcm_count = 0;

    int32_t *ch[8];
    for (int i = 0; i < 8; ++i) ch[i] = NULL;
    sleela_codec_result rc = SLEELA_CODEC_OK;

    while (b.byte < b.len) {
        br_align(&b);
        /* Frame sync: 14 bits = 0x3FFE. */
        uint32_t sync = br_bits(&b, 14);
        if (b.error) break;                           /* clean end of stream */
        if (sync != 0x3FFEu) { rc = SLEELA_CODEC_ERR_FORMAT; break; }
        (void)br_bit(&b);                             /* reserved */
        unsigned blocking = br_bit(&b);               /* 0 fixed, 1 variable */
        unsigned bs_code = br_bits(&b, 4);
        unsigned sr_code = br_bits(&b, 4);
        unsigned ch_assign = br_bits(&b, 4);
        (void)br_bits(&b, 3);                         /* sample size code */
        (void)br_bit(&b);                             /* reserved */

        unsigned first = br_bits(&b, 8);              /* UTF-8 coded number */
        skip_utf8_coded(&b, first);
        (void)blocking;

        /* Block size. */
        unsigned block_size;
        if (bs_code == 1) block_size = 192;
        else if (bs_code >= 2 && bs_code <= 5) block_size = 576u << (bs_code - 2);
        else if (bs_code == 6) block_size = br_bits(&b, 8) + 1;
        else if (bs_code == 7) block_size = br_bits(&b, 16) + 1;
        else if (bs_code >= 8 && bs_code <= 15) block_size = 256u << (bs_code - 8);
        else { rc = SLEELA_CODEC_ERR_FORMAT; break; } /* bs_code 0 reserved */

        /* Sample-rate code: consume the "get from header" trailers if present. */
        if (sr_code == 12) (void)br_bits(&b, 8);
        else if (sr_code == 13 || sr_code == 14) (void)br_bits(&b, 16);

        (void)br_bits(&b, 8);                         /* frame header CRC-8 */
        if (b.error) { rc = SLEELA_CODEC_ERR_FORMAT; break; }

        /* Channel assignment: 0..7 = independent channels (count = code+1);
         * 8 = left/side, 9 = right/side, 10 = mid/side (all stereo). */
        unsigned nch, stereo_mode = 0;
        if (ch_assign <= 7) { nch = ch_assign + 1; }
        else if (ch_assign >= 8 && ch_assign <= 10) { nch = 2; stereo_mode = ch_assign; }
        else { rc = SLEELA_CODEC_ERR_FORMAT; break; }
        if (nch != si.channels) { rc = SLEELA_CODEC_ERR_FORMAT; break; }

        for (unsigned c = 0; c < nch; ++c) {
            ch[c] = (int32_t *)malloc(block_size * sizeof(int32_t));
            if (!ch[c]) { rc = SLEELA_CODEC_ERR_IO; break; }
            /* Side channels in a decorrelated stereo frame carry one extra bit. */
            unsigned bps = si.bits_per_sample;
            if ((stereo_mode == 8 && c == 1) ||       /* left/side -> side is ch 1 */
                (stereo_mode == 9 && c == 0) ||       /* right/side -> side is ch 0 */
                (stereo_mode == 10 && c == 1))        /* mid/side -> side is ch 1 */
                bps += 1;
            int sr = read_subframe(&b, ch[c], block_size, bps);
            if (sr != 0) { rc = (sr == 2) ? SLEELA_CODEC_ERR_UNSUPPORTED : SLEELA_CODEC_ERR_FORMAT; break; }
        }
        if (rc != SLEELA_CODEC_OK) { for (unsigned c = 0; c < nch; ++c) { free(ch[c]); ch[c] = NULL; } break; }

        br_align(&b);
        (void)br_bits(&b, 16);                        /* frame footer CRC-16 */

        /* Undo stereo decorrelation into independent L/R. */
        if (stereo_mode == 8) {                        /* left/side */
            for (unsigned i = 0; i < block_size; ++i) ch[1][i] = ch[0][i] - ch[1][i];
        } else if (stereo_mode == 9) {                 /* right/side */
            for (unsigned i = 0; i < block_size; ++i) ch[0][i] = ch[0][i] + ch[1][i];
        } else if (stereo_mode == 10) {                /* mid/side */
            for (unsigned i = 0; i < block_size; ++i) {
                int32_t mid = ch[0][i], side = ch[1][i];
                mid = (mid << 1) | (side & 1);
                ch[0][i] = (mid + side) >> 1;
                ch[1][i] = (mid - side) >> 1;
            }
        }

        /* Grow the interleaved buffer if needed, then append this block. */
        size_t need = pcm_count + (size_t)block_size * nch;
        if (need > cap) {
            size_t ncap = cap ? cap : 4096;
            while (ncap < need) ncap *= 2;
            int16_t *np = (int16_t *)realloc(pcm, ncap * sizeof(int16_t));
            if (!np) { rc = SLEELA_CODEC_ERR_IO; for (unsigned c = 0; c < nch; ++c) free(ch[c]); break; }
            pcm = np; cap = ncap;
        }
        for (unsigned i = 0; i < block_size; ++i)
            for (unsigned c = 0; c < nch; ++c) {
                int32_t v = ch[c][i];
                if (v > 32767) v = 32767; else if (v < -32768) v = -32768;
                pcm[pcm_count++] = (int16_t)v;
            }
        for (unsigned c = 0; c < nch; ++c) { free(ch[c]); ch[c] = NULL; }
    }

    if (rc != SLEELA_CODEC_OK) { free(pcm); return rc; }
    if (pcm_count == 0) { free(pcm); return SLEELA_CODEC_ERR_FORMAT; }

    out->samples = pcm;
    out->channels = si.channels;
    out->sample_rate = si.sample_rate ? si.sample_rate : 44100;
    out->frame_count = pcm_count / si.channels;
    return SLEELA_CODEC_OK;
}

static sleela_codec_result flac_encode(const sleela_pcm_buffer *pcm,
                                       uint8_t *output, size_t *inout_len) {
    (void)pcm; (void)output; (void)inout_len;
    return SLEELA_CODEC_ERR_UNSUPPORTED;               /* decode-only backend */
}

static const sleela_codec_backend k_backend = {
    "flac-native (in-tree, CONSTANT/VERBATIM/FIXED)",
    flac_decode,
    flac_encode
};

const sleela_codec_backend *sleela_flac_native_backend(void) { return &k_backend; }

sleela_codec_result sleela_flac_native_register(void) {
    return sleela_codec_backend_register(SLEELA_CODEC_FLAC, &k_backend);
}

sleela_codec_result sleela_flac_native_unregister(void) {
    return sleela_codec_backend_register(SLEELA_CODEC_FLAC, NULL);
}