carta1 1.1.7 → 1.1.9

package/codec/coding/bitallocation.js

@@ -5,21 +5,20 @@
  * responsible for distributing available bits across frequency bands to minimize
  * perceptual distortion while maintaining the target bitrate.
  *
- * The module uses Rate-Distortion Optimization (RDO) with a greedy algorithm
- * that allocates bits to Band Frequency Units (BFUs) based on the perceptual
- * benefit per bit spent. It employs psychoacoustic modeling to determine
- * scale factors and uses a priority queue to efficiently find the optimal
- * bit distribution.
+ * The module uses Rate-Distortion Optimization (RDO) by searching over a
+ * predefined set of valid Band Frequency Unit (BFU) counts. For each count,
+ * it performs a greedy bit distribution to find the best allocation. This
+ * approach optimally trades off the cost of encoding more frequency bands
+ * (metadata overhead) against the benefit of reducing truncation distortion.
  *
  * Key components:
- * - RDO-based bit allocation using exponential distortion modeling
- * - Scale factor computation for each frequency band
- * - Max-heap priority queue for greedy optimization
- * - Support for variable word lengths per BFU
+ * - RDO search over valid BFU counts to select the optimal number of bands.
+ * - Greedy bit allocation for a fixed BFU count using a max-heap.
+ * - Exponential distortion modeling based on scale factors.
+ * - Support for variable word lengths per BFU.
  *
- * The algorithm ensures that bits are allocated where they provide the
- * greatest reduction in audible distortion, resulting in high-quality
- * audio compression at the target bitrate.
+ * The algorithm ensures that the codec dynamically adapts the encoded bandwidth
+ * to best match the signal characteristics for the given bitrate.
  */
 
 import {
@@ -31,10 +30,41 @@ import {
   WORD_LENGTH_BITS,
   INV_POWER_OF_TWO,
   SCALE_FACTORS,
+  BFU_AMOUNTS,
+  WORD_LENGTH_DELTA_BITS,
+  DISTORTION_DELTA_FACTORS,
 } from '../core/constants.js'
 
+const biasedScaleFactorCache = new Map()
+
+/**
+ * Builds and returns a cached table of biased scale factors.
+ *
+ * @param {number} bias
+ * @returns {Float64Array}
+ */
+function buildBiasedScaleFactorTable(bias) {
+  if (biasedScaleFactorCache.has(bias)) {
+    return biasedScaleFactorCache.get(bias)
+  }
+
+  const out = new Float64Array(64)
+  if (bias === 1) {
+    out.set(SCALE_FACTORS)
+  } else {
+    for (let i = 0; i < 64; i++) {
+      out[i] = Math.pow(SCALE_FACTORS[i], bias)
+    }
+  }
+  biasedScaleFactorCache.set(bias, out)
+  return out
+}
+
 /**
- * Allocate bits to BFUs using optimized greedy Lp-RDO
+ * Allocate bits by finding the optimal BFU count and distribution using RDO.
+ * This function searches through the valid BFU counts to find the one that
+ * minimizes the total perceptual distortion.
+ *
  * @param {Array<Float32Array>} bfuData
  * @param {Int32Array} bfuSizes
  * @param {number} maxBfuCount
@@ -42,136 +72,224 @@ import {
  * @returns {{bfuCount:number, allocation:Int32Array, scaleFactorIndices:Int32Array}}
  */
 export function allocateBits(bfuData, bfuSizes, maxBfuCount, allocationBias) {
-  const usedBFU = maxBfuCount
-  const avail =
-    FRAME_BITS - FRAME_OVERHEAD_BITS - usedBFU * BITS_PER_BFU_METADATA
-
-  const rdoResult = distributeBitsRDO(
-    usedBFU,
-    bfuData,
-    bfuSizes,
-    avail,
-    allocationBias
-  )
-
-  return {
-    bfuCount: usedBFU,
-    allocation: rdoResult.wordLengths,
-    scaleFactorIndices: rdoResult.scaleFactorIndices,
+  const allScaleFactorIndices = new Int32Array(maxBfuCount)
+  const zeroBitDistortions = new Float32Array(maxBfuCount)
+  const biasedScaleFactors = buildBiasedScaleFactorTable(allocationBias)
+
+  for (let i = 0; i < maxBfuCount; i++) {
+    const sz = bfuSizes[i] | 0
+    if (sz === 0) continue
+
+    const sfi = findScaleFactor(bfuData[i], sz)
+    allScaleFactorIndices[i] = sfi
+    if (sfi > 0) {
+      const effectiveScaleFactor = biasedScaleFactors[sfi]
+      zeroBitDistortions[i] = effectiveScaleFactor * 2.0 * sz
+    }
+  }
+
+  let bestResult = null
+  let minTotalDistortion = Infinity
+
+  for (const candidateBfuCount of BFU_AMOUNTS) {
+    if (candidateBfuCount > maxBfuCount) continue
+
+    const availableBits =
+      FRAME_BITS -
+      FRAME_OVERHEAD_BITS -
+      candidateBfuCount * BITS_PER_BFU_METADATA
+
+    if (availableBits < 0) continue
+
+    const rdoResult = distributeBitsRDO(
+      candidateBfuCount,
+      bfuSizes,
+      availableBits,
+      biasedScaleFactors,
+      allScaleFactorIndices
+    )
+
+    const totalDistortion = calculateTotalDistortion(
+      candidateBfuCount,
+      maxBfuCount,
+      bfuSizes,
+      rdoResult.wordLengths,
+      rdoResult.scaleFactorIndices,
+      biasedScaleFactors,
+      zeroBitDistortions
+    )
+
+    if (totalDistortion < minTotalDistortion) {
+      minTotalDistortion = totalDistortion
+      bestResult = {
+        bfuCount: candidateBfuCount,
+        allocation: rdoResult.wordLengths,
+        scaleFactorIndices: rdoResult.scaleFactorIndices,
+      }
+    }
   }
+
+  if (!bestResult) {
+    const fallbackBfuCount = BFU_AMOUNTS[0]
+    return {
+      bfuCount: fallbackBfuCount,
+      allocation: new Int32Array(fallbackBfuCount),
+      scaleFactorIndices: new Int32Array(NUM_BFUS),
+    }
+  }
+
+  return bestResult
+}
+
+/**
+ * Calculates the total distortion for a given allocation.
+ * This includes quantization distortion for coded bands and truncation
+ * distortion for uncoded bands.
+ * @param {number} activeBfuCount
+ * @param {number} maxBfuCount
+ * @param {Int32Array} bfuSizes
+ * @param {Int32Array} wordLengths
+ * @param {Int32Array} scaleFactorIndices
+ * @param {number} biasedScaleFactors
+ * @param {Float32Array} zeroBitDistortions
+ * @returns {number}
+ */
+function calculateTotalDistortion(
+  activeBfuCount,
+  maxBfuCount,
+  bfuSizes,
+  wordLengths,
+  scaleFactorIndices,
+  biasedScaleFactors,
+  zeroBitDistortions
+) {
+  let totalDistortion = 0.0
+
+  for (let i = 0; i < activeBfuCount; i++) {
+    const wl = wordLengths[i] | 0
+    const bits = WORD_LENGTH_BITS[wl] | 0
+    if (bits === 0) {
+      totalDistortion += zeroBitDistortions[i]
+      continue
+    }
+
+    const sfi = scaleFactorIndices[i]
+    if (sfi === 0) continue
+
+    const effectiveScaleFactor = biasedScaleFactors[sfi]
+    const distortionFactor = INV_POWER_OF_TWO[bits]
+
+    totalDistortion += effectiveScaleFactor * distortionFactor * bfuSizes[i]
+  }
+
+  for (let i = activeBfuCount; i < maxBfuCount; i++) {
+    totalDistortion += zeroBitDistortions[i]
+  }
+
+  return totalDistortion
 }
 
 /**
  * Distributes available bits across Band Frequency Units (BFUs) using Rate-Distortion Optimization.
- *
- * This function implements an optimized greedy RDO allocator that minimizes perceptual distortion
- * while staying within the bit budget. It uses a priority queue (max-heap) to greedily allocate
- * bits to the BFUs that provide the greatest distortion reduction per bit spent.
+ * (Modified to accept pre-calculated scale factors)
  *
  * @param {number} activeBfuCount
- * @param {Array<Float32Array>} bfuData
  * @param {Int32Array} bfuSizes
  * @param {number} remainingBits
- * @param {number} allocationBias
+ * @param {Float64Array} biasedScaleFactors
+ * @param {Int32Array} allScaleFactorIndices
  * @returns {{wordLengths: Int32Array, scaleFactorIndices: Int32Array}}
  */
 function distributeBitsRDO(
   activeBfuCount,
-  bfuData,
   bfuSizes,
   remainingBits,
-  allocationBias
+  biasedScaleFactors,
+  allScaleFactorIndices
 ) {
-  const scaleFactorTable = new Int32Array(NUM_BFUS)
   const wordLengths = new Int32Array(activeBfuCount)
 
-  const heapIndices = []
-  const heapPriorities = []
-
-  const deltaDistPerCoeff = (bfuIndex, currentWl, nextWl) => {
-    const sfi = scaleFactorTable[bfuIndex]
-    const scaleFactor = SCALE_FACTORS[sfi]
-    if (scaleFactor === 0) return 0
-
-    const effectiveScaleFactor = Math.pow(scaleFactor, allocationBias)
-
-    const bits1 = WORD_LENGTH_BITS[currentWl] | 0
-    const bits2 = WORD_LENGTH_BITS[nextWl] | 0
-
-    const f1 = bits1 === 0 ? 2.0 : INV_POWER_OF_TWO[bits1]
-    const f2 = INV_POWER_OF_TWO[bits2]
-
-    return effectiveScaleFactor * (f1 - f2)
-  }
+  const heapIndices = new Int32Array(activeBfuCount)
+  const heapPriorities = new Float32Array(activeBfuCount)
+  let heapSize = 0
 
   for (let bfuIndex = 0; bfuIndex < activeBfuCount; bfuIndex++) {
     const sz = bfuSizes[bfuIndex] | 0
     if (sz === 0) continue
 
-    const sfi = findScaleFactor(bfuData[bfuIndex].subarray(0, sz))
-    scaleFactorTable[bfuIndex] = sfi
-
+    const sfi = allScaleFactorIndices[bfuIndex]
     if (sfi === 0) continue
 
-    const currentWl = 0
-    const nextWl = 1
-    const deltaBits =
-      (WORD_LENGTH_BITS[nextWl] - WORD_LENGTH_BITS[currentWl]) | 0
+    const deltaBits = WORD_LENGTH_DELTA_BITS[0]
     if (deltaBits <= 0) continue
 
-    const ddPerCoeff = deltaDistPerCoeff(bfuIndex, currentWl, nextWl)
-    heapIndices.push(bfuIndex)
-    heapPriorities.push(ddPerCoeff / deltaBits)
+    const distortionDelta =
+      biasedScaleFactors[sfi] * DISTORTION_DELTA_FACTORS[0]
+
+    heapIndices[heapSize] = bfuIndex
+    heapPriorities[heapSize] = distortionDelta / deltaBits
+    heapSize++
+  }
+
+  if (heapSize === 0) {
+    return { wordLengths, scaleFactorIndices: allScaleFactorIndices }
   }
 
   // Heapify
-  for (let i = (heapIndices.length >> 1) - 1; i >= 0; i--)
-    siftDown(heapIndices, heapPriorities, i)
+  for (let i = (heapSize >> 1) - 1; i >= 0; i--) {
+    siftDown(heapIndices, heapPriorities, i, heapSize)
+  }
 
-  // Greedy spending
-  while (remainingBits > 0 && heapIndices.length > 0) {
+  // Greedy spending loop
+  while (remainingBits > 0 && heapSize > 0) {
     const bfu = heapIndices[0]
     const cur = wordLengths[bfu] | 0
-    const nxt = cur + 1
-
     const sz = bfuSizes[bfu] | 0
-    const deltaBits = (WORD_LENGTH_BITS[nxt] - WORD_LENGTH_BITS[cur]) | 0
+    const deltaBits = WORD_LENGTH_DELTA_BITS[cur]
     const cost = deltaBits * sz
 
     if (cost > remainingBits || cost <= 0) {
-      popRoot(heapIndices, heapPriorities)
+      const last = heapSize - 1
+      heapIndices[0] = heapIndices[last]
+      heapPriorities[0] = heapPriorities[last]
+      heapSize--
+      if (heapSize > 0) siftDown(heapIndices, heapPriorities, 0, heapSize)
       continue
     }
 
     remainingBits -= cost
+    const nxt = cur + 1
     wordLengths[bfu] = nxt
 
-    if (nxt < MAX_WORD_LENGTH_INDEX) {
-      const nxt2 = nxt + 1
-      const deltaBits2 = (WORD_LENGTH_BITS[nxt2] - WORD_LENGTH_BITS[nxt]) | 0
-      if (deltaBits2 > 0) {
-        heapPriorities[0] = deltaDistPerCoeff(bfu, nxt, nxt2) / deltaBits2
-        siftDown(heapIndices, heapPriorities, 0)
-      } else {
-        popRoot(heapIndices, heapPriorities)
-      }
+    const deltaBitsNext = WORD_LENGTH_DELTA_BITS[nxt]
+    if (nxt < MAX_WORD_LENGTH_INDEX && deltaBitsNext > 0) {
+      const sfi = allScaleFactorIndices[bfu]
+      const distortionDelta =
+        biasedScaleFactors[sfi] * DISTORTION_DELTA_FACTORS[nxt]
+      heapPriorities[0] = distortionDelta / deltaBitsNext
+      siftDown(heapIndices, heapPriorities, 0, heapSize)
     } else {
-      popRoot(heapIndices, heapPriorities)
+      const last = heapSize - 1
+      heapIndices[0] = heapIndices[last]
+      heapPriorities[0] = heapPriorities[last]
+      heapSize--
+      if (heapSize > 0) siftDown(heapIndices, heapPriorities, 0, heapSize)
     }
   }
 
-  return { wordLengths, scaleFactorIndices: scaleFactorTable }
+  return { wordLengths, scaleFactorIndices: allScaleFactorIndices }
 }
 
 /**
  * Find the optimal scale factor index for a set of coefficients.
  * Same semantics as the original.
  * @param {Float32Array} coefficients
+ * @param {number} length
  * @returns {number}
  */
-export function findScaleFactor(coefficients) {
+export function findScaleFactor(coefficients, length) {
   let maxAmplitude = 0.0
-  for (let i = 0; i < coefficients.length; i++) {
+  for (let i = 0; i < length; i++) {
     const a = Math.abs(coefficients[i])
     if (a > maxAmplitude) maxAmplitude = a
   }
@@ -180,25 +298,6 @@ export function findScaleFactor(coefficients) {
   return Math.max(0, Math.min(63, index))
 }
 
-/**
- * Removes the root element from a max-heap and maintains heap property.
- *
- * This function efficiently removes the maximum priority element from the heap
- * by replacing it with the last element and then restoring the heap property
- * through sifting down.
- *
- * @param {Array<number>} heapIndices
- * @param {Array<number>} heapPriorities
- */
-function popRoot(heapIndices, heapPriorities) {
-  const last = heapIndices.length - 1
-  heapIndices[0] = heapIndices[last]
-  heapPriorities[0] = heapPriorities[last]
-  heapIndices.pop()
-  heapPriorities.pop()
-  if (heapIndices.length) siftDown(heapIndices, heapPriorities, 0)
-}
-
 /**
  * Restores max-heap property by sifting an element down from a given position.
  *
@@ -207,12 +306,12 @@ function popRoot(heapIndices, heapPriorities) {
  * with its children and swaps with the larger child until the heap property
  * is satisfied, or it reaches a leaf position.
  *
- * @param {Array<number>} heapIndices
- * @param {Array<number>} heapPriorities
+ * @param {Int32Array} heapIndices
+ * @param {Float32Array} heapPriorities
  * @param {number} startIndex
+ * @param {number} heapSize
  */
-function siftDown(heapIndices, heapPriorities, startIndex) {
-  const heapSize = heapIndices.length
+function siftDown(heapIndices, heapPriorities, startIndex, heapSize) {
   let i = startIndex
   const idxVal = heapIndices[i]
   const prVal = heapPriorities[i]

package/codec/core/constants.js

@@ -158,3 +158,22 @@ export const INV_POWER_OF_TWO = (() => {
   }
   return table
 })()
+
+export const WORD_LENGTH_DELTA_BITS = (() => {
+  const table = new Int32Array(MAX_WORD_LENGTH_INDEX)
+  for (let i = 0; i < MAX_WORD_LENGTH_INDEX; i++) {
+    table[i] = (WORD_LENGTH_BITS[i + 1] - WORD_LENGTH_BITS[i]) | 0
+  }
+  return table
+})()
+
+export const DISTORTION_DELTA_FACTORS = (() => {
+  const table = new Float64Array(MAX_WORD_LENGTH_INDEX)
+  table[0] = 2.0 - INV_POWER_OF_TWO[WORD_LENGTH_BITS[1]]
+  for (let i = 1; i < MAX_WORD_LENGTH_INDEX; i++) {
+    const bits1 = WORD_LENGTH_BITS[i] | 0
+    const bits2 = WORD_LENGTH_BITS[i + 1] | 0
+    table[i] = INV_POWER_OF_TWO[bits1] - INV_POWER_OF_TWO[bits2]
+  }
+  return table
+})()

package/codec/core/options.js

@@ -52,7 +52,7 @@ class EncoderOptions {
         name: 'Bit allocation bias',
         description:
           'Controls how bits are distributed across the frequency spectrum during allocation. Higher values focus more bits on loud spectral components, while lower values spread bits more evenly across frequencies.',
-        range: [0.5, 3.0],
+        range: [0.0, 5.0],
         step: 0.01,
       },
       fixedBlockModes: {

package/codec/pipeline/encoder.js

@@ -392,11 +392,16 @@ export function quantizationStage(context) {
       scaleFactorIndices,
     } = allocateBits(bfuData, bfuSizes, bfuCount, options.allocationBias)
 
+    const slicedWordLengthIndices = allocation.slice(0, selectedBfuCount)
+    const slicedScaleFactorIndices = scaleFactorIndices.slice(
+      0,
+      selectedBfuCount
+    )
     const quantizedCoefficients = []
 
     for (let bfu = 0; bfu < selectedBfuCount; bfu++) {
       const data = bfuData[bfu].subarray(0, bfuSizes[bfu])
-      const wordLength = allocation[bfu]
+      const wordLength = slicedWordLengthIndices[bfu]
       const bitsPerSample = WORD_LENGTH_BITS[wordLength]
       const quantized = quantize(data, scaleFactorIndices[bfu], bitsPerSample)
       quantizedCoefficients.push(quantized)
@@ -404,8 +409,8 @@ export function quantizationStage(context) {
 
     return {
       nBfu: selectedBfuCount,
-      scaleFactorIndices,
-      wordLengthIndices: allocation.slice(0, selectedBfuCount),
+      scaleFactorIndices: slicedScaleFactorIndices,
+      wordLengthIndices: slicedWordLengthIndices,
       quantizedCoefficients,
       blockModes,
     }