carta1 1.0.22 → 1.1.0

package/codec/browser/interface.js

@@ -71,7 +71,6 @@ class Carta1Worker {
    * @param {number} [options.transientThresholdLow] - Low band transient threshold
    * @param {number} [options.transientThresholdMid] - Mid band transient threshold
    * @param {number} [options.transientThresholdHigh] - High band transient threshold
-   * @param {number} [options.normalizationDb] - Normalization level in dB
    * @returns {Promise<Object>} Encoding result
    * @returns {Blob} returns.aeaBlob - ATRAC1 encoded audio blob
    * @returns {Object} returns.shortBlockData - Short block frame indices

package/codec/coding/bitallocation.js

@@ -1,317 +1,275 @@
 /**
  * Carta1 Audio Codec - Bit Allocation Module
  *
- * This module implements the bit allocation algorithm for ATRAC1 compression,
- * distributing available bits among Block Floating Units (BFUs) based on
- * psychoacoustic masking and signal-to-mask ratios.
+ * This module implements the bit allocation system for the Carta1 audio codec,
+ * 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.
+ *
+ * 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
+ *
+ * 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.
  */
+
 import {
+  NUM_BFUS,
   FRAME_BITS,
   FRAME_OVERHEAD_BITS,
   BITS_PER_BFU_METADATA,
-  BFU_AMOUNTS,
   MAX_WORD_LENGTH_INDEX,
   WORD_LENGTH_BITS,
-  DISTORTION_DELTA_DB,
-  PSYMODEL_MIN_POWER_DB,
-  INTERPOLATION_COMPENSATION_FACTOR,
-  BFU_MASK_INTERPOLATION_TABLE,
-  BFU_FREQUENCIES,
-  NUM_BFUS,
-  SAMPLE_RATE,
-  PSYMODEL_FFT_SIZE,
+  LP_DISTORTION_CONSTANT,
+  SF_POW_P,
+  POW2_POS_P,
+  POW2_NEG_P,
+  SCALE_FACTORS,
 } from '../core/constants.js'
 
 /**
- * Allocate bits to BFUs based on psychoacoustic analysis
- * @param {Object} psychoResults - Psychoacoustic analysis results
- * @param {Array} bfuData - BFU coefficient data
- * @param {Array} bfuSizes - Size of each BFU
- * @param {number} maxBfuCount - Maximum number of BFUs to use
- * @returns {Object} Allocation results with BFU count and bit distribution
+ * Allocate bits to BFUs using optimized greedy Lp-RDO
+ * @param {Array<Float32Array>} bfuData
+ * @param {Int32Array} bfuSizes
+ * @param {number} maxBfuCount
+ * @returns {{bfuCount:number, allocation:Int32Array, scaleFactorIndices:Int32Array}}
  */
-export function allocateBits(psychoResults, bfuData, bfuSizes, maxBfuCount) {
-  const energyDb = calculateBfuEnergy(bfuData, bfuSizes, maxBfuCount)
-  const maskDb = interpolateMask(psychoResults.criticalBandThresholds)
-  const smr = calculateSMR(energyDb, maskDb, maxBfuCount)
-  const usedBFU = selectOptimalBfuCount(smr, energyDb, maxBfuCount)
+export function allocateBits(bfuData, bfuSizes, maxBfuCount) {
+  const usedBFU = maxBfuCount
   const avail =
     FRAME_BITS - FRAME_OVERHEAD_BITS - usedBFU * BITS_PER_BFU_METADATA
-  const allocation = distributeBitsGreedy(usedBFU, smr, bfuSizes, avail)
-  return { bfuCount: usedBFU, allocation }
-}
 
-/**
- * Calculate energy in dB for each BFU
- * @param {Array} bfuData - BFU coefficient bfuData
- * @param {Array} bfuSizes - Size of each BFU
- * @param {number} bfuCount - Number of BFUs to process
- * @returns {Float32Array} Energy values in dB
- */
-function calculateBfuEnergy(bfuData, bfuSizes, bfuCount) {
-  const out = new Float32Array(bfuCount)
-  const minDb = PSYMODEL_MIN_POWER_DB
-  for (let i = 0; i < bfuCount; i++) {
-    const sz = bfuSizes[i]
-    if (!sz) {
-      out[i] = minDb
-      continue
-    }
-    let sum = 0,
-      buf = bfuData[i]
-    for (let j = 0; j < sz; j++) sum += buf[j] * buf[j]
-    out[i] = sum > 0 ? 10 * Math.log10(sum / sz) : minDb
+  const rdoResult = distributeBitsRDO(usedBFU, bfuData, bfuSizes, avail)
+
+  return {
+    bfuCount: usedBFU,
+    allocation: rdoResult.wordLengths,
+    scaleFactorIndices: rdoResult.scaleFactorIndices,
   }
-  return out
 }
 
 /**
- * Interpolate psychoacoustic masking thresholds from critical bands to BFU frequencies
- * @param {Float32Array} criticalBandThresholds - Masking thresholds for each critical band
- * @returns {Float32Array} Interpolated masking thresholds for each BFU
+ * 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.
+ *
+ * Mathematical Model:
+ * Distortion for b bits is modeled as:
+ *   D(b) = C * 2^{-p * b}            for b >= 1
+ *   D(0) = C * 2^{ p }               (finite large step for "mute" case)
+ * where C = N * (sf^p) * k, with N = BFU length, sf = scale factor, p and k constants.
+ *
+ * Hence, for an upgrade from b1 -> b2 (b2 > b1), ΔD = D(b1) - D(b2) can be computed with 2 table lookups.
+ *
+ * Precomputed tables:
+ *   POW2_NEG_P[b] = 2^{-p*b}   for b=0..maxBits
+ *   POW2_POS_P    = 2^{ p}
+ *   SF_POW_P[sfIndex] = (SCALE_FACTORS[sfIndex])^p
+ *
+ * @param {number} activeBfuCount
+ * @param {Array<Float32Array>} bfuData
+ * @param {Int32Array} bfuSizes
+ * @param {number} remainingBits
+ * @returns {{wordLengths: Int32Array, scaleFactorIndices: Int32Array}}
  */
-function interpolateMask(criticalBandThresholds) {
-  const maskValues = new Float32Array(NUM_BFUS)
-
-  for (let bfuIndex = 0; bfuIndex < NUM_BFUS; bfuIndex++) {
-    const interpolationEntry = BFU_MASK_INTERPOLATION_TABLE[bfuIndex]
-    const currentBandThreshold = criticalBandThresholds[interpolationEntry.band]
-    const nextBandThreshold = criticalBandThresholds[interpolationEntry.next]
-
-    // Calculate interpolation parameter t based on BFU frequency position
-    const normalizedFreqPosition =
-      (Math.round(
-        BFU_FREQUENCIES[bfuIndex] / (SAMPLE_RATE / PSYMODEL_FFT_SIZE)
-      ) -
-        interpolationEntry.x0) *
-      interpolationEntry.tInv
-
-    const interpolatedValue =
-      currentBandThreshold +
-      (nextBandThreshold - currentBandThreshold) * normalizedFreqPosition
+function distributeBitsRDO(activeBfuCount, bfuData, bfuSizes, remainingBits) {
+  const scaleFactorTable = new Int32Array(NUM_BFUS)
+  const wordLengths = new Int32Array(activeBfuCount)
 
-    // Add compensation factor based on threshold difference
-    maskValues[bfuIndex] =
-      interpolatedValue +
-      Math.abs(nextBandThreshold - currentBandThreshold) *
-        INTERPOLATION_COMPENSATION_FACTOR
+  const baseWeight = new Float64Array(activeBfuCount) // C above
+  for (let bfuIndex = 0; bfuIndex < activeBfuCount; bfuIndex++) {
+    const sz = bfuSizes[bfuIndex] | 0
+    if (sz > 0) {
+      const sfi = findScaleFactor(bfuData[bfuIndex].subarray(0, sz))
+      scaleFactorTable[bfuIndex] = sfi
+      baseWeight[bfuIndex] = sz * SF_POW_P[sfi] * LP_DISTORTION_CONSTANT
+    } else {
+      scaleFactorTable[bfuIndex] = 0
+      baseWeight[bfuIndex] = 0
+    }
   }
 
-  return maskValues
-}
+  const heapIndices = []
+  const heapPriorities = []
+  const deltaDist = (bfuIndex, currentWl, nextWl) => {
+    const base = baseWeight[bfuIndex]
+    if (base === 0) return 0
 
-/**
- * Calculate Signal-to-Mask Ratios (SMR) for each BFU
- * SMR determines how much energy exceeds the masking threshold
- * @param {Float32Array} energyDb - Energy values in dB for each BFU
- * @param {Float32Array} maskDb - Masking threshold values in dB for each BFU
- * @param {number} bfuCount - Number of BFUs to process
- * @returns {Float32Array} SMR values for each BFU (-Infinity for inaudible BFUs)
- */
-function calculateSMR(energyDb, maskDb, bfuCount) {
-  const smrValues = new Float32Array(bfuCount)
+    const bits1 = WORD_LENGTH_BITS[currentWl] | 0
+    const bits2 = WORD_LENGTH_BITS[nextWl] | 0
 
-  for (let bfuIndex = 0; bfuIndex < bfuCount; bfuIndex++) {
-    const energyValue = energyDb[bfuIndex]
-    smrValues[bfuIndex] =
-      energyValue <= PSYMODEL_MIN_POWER_DB
-        ? -Infinity
-        : energyValue - maskDb[bfuIndex]
+    const f1 = bits1 === 0 ? POW2_POS_P : POW2_NEG_P[bits1]
+    const f2 = POW2_NEG_P[bits2]
+
+    return base * (f1 - f2)
   }
 
-  return smrValues
-}
+  for (let bfuIndex = 0; bfuIndex < activeBfuCount; bfuIndex++) {
+    const sz = bfuSizes[bfuIndex] | 0
+    if (sz === 0) continue
+    if (scaleFactorTable[bfuIndex] === 0) continue
 
-/**
- * Determine optimal number of BFUs to use based on SMR analysis
- * Uses cumulative SMR analysis to find the point of diminishing returns
- * @param {Float32Array} smrValues - Signal-to-Mask ratios for each BFU
- * @param {Float32Array} energyValues - Energy values for each BFU
- * @param {number} maxBfuCount - Maximum BFUs available
- * @returns {number} Optimal number of BFUs to use for encoding
- */
-function selectOptimalBfuCount(smrValues, energyValues, maxBfuCount) {
-  // Collect BFUs with positive SMR (above masking threshold)
-  const positiveSMRBfus = []
-  for (let bfuIndex = 0; bfuIndex < maxBfuCount; bfuIndex++) {
-    if (smrValues[bfuIndex] > 0) {
-      positiveSMRBfus.push({
-        index: bfuIndex,
-        smrValue: smrValues[bfuIndex],
-      })
-    }
-  }
+    const currentWl = 0
+    const nextWl = 1
+    const deltaBits =
+      (WORD_LENGTH_BITS[nextWl] - WORD_LENGTH_BITS[currentWl]) | 0
+    if (deltaBits <= 0) continue
 
-  // If no BFUs have positive SMR, fall back to energy-based selection
-  if (!positiveSMRBfus.length) {
-    for (let bfuIndex = maxBfuCount - 1; bfuIndex >= 0; bfuIndex--) {
-      if (energyValues[bfuIndex] > PSYMODEL_MIN_POWER_DB) {
-        return (
-          BFU_AMOUNTS.find((count) => count > bfuIndex) ||
-          BFU_AMOUNTS[BFU_AMOUNTS.length - 1]
-        )
-      }
-    }
-    return BFU_AMOUNTS[0]
+    const deltaCost = deltaBits * sz
+    const dd = deltaDist(bfuIndex, currentWl, nextWl)
+
+    heapIndices.push(bfuIndex)
+    heapPriorities.push(dd / deltaCost) // priority = ΔD / ΔR
   }
 
-  // Sort BFUs by SMR value (highest first)
-  positiveSMRBfus.sort((a, b) => b.smrValue - a.smrValue)
+  // Heapify
+  for (let i = (heapIndices.length >> 1) - 1; i >= 0; i--)
+    siftDown(heapIndices, heapPriorities, i)
 
-  // Calculate cumulative SMR values
-  const cumulativeSmr = new Float32Array(positiveSMRBfus.length)
-  cumulativeSmr[0] = positiveSMRBfus[0].smrValue
-  for (let k = 1; k < positiveSMRBfus.length; k++) {
-    cumulativeSmr[k] = cumulativeSmr[k - 1] + positiveSMRBfus[k].smrValue
-  }
+  // Greedy spending
+  while (remainingBits > 0 && heapIndices.length > 0) {
+    const bfu = heapIndices[0]
+    const cur = wordLengths[bfu] | 0
+    const nxt = cur + 1
 
-  // Find optimal cutoff point using diminishing returns analysis
-  for (const candidateCount of BFU_AMOUNTS) {
-    if (candidateCount > maxBfuCount) continue
-    if (positiveSMRBfus.length <= candidateCount) return candidateCount
+    const sz = bfuSizes[bfu] | 0
+    const deltaBits = (WORD_LENGTH_BITS[nxt] - WORD_LENGTH_BITS[cur]) | 0
+    const cost = deltaBits * sz
 
-    const lastIncludedIndex = candidateCount - 1
-    const averageIncludedSmr =
-      cumulativeSmr[lastIncludedIndex] / (lastIncludedIndex + 1)
-    const averageExcludedSmr =
-      (cumulativeSmr[positiveSMRBfus.length - 1] -
-        cumulativeSmr[lastIncludedIndex]) /
-      (positiveSMRBfus.length - lastIncludedIndex - 1)
+    if (cost > remainingBits || cost <= 0) {
+      popRoot(heapIndices, heapPriorities)
+      continue
+    }
 
-    // If excluded BFUs contribute less than 10% of included average, use this count
-    if (averageExcludedSmr < averageIncludedSmr * 0.1) return candidateCount
+    remainingBits -= cost
+    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] = deltaDist(bfu, nxt, nxt2) / (deltaBits2 * sz)
+        siftDown(heapIndices, heapPriorities, 0)
+      } else {
+        popRoot(heapIndices, heapPriorities)
+      }
+    } else {
+      popRoot(heapIndices, heapPriorities)
+    }
   }
 
-  return BFU_AMOUNTS[BFU_AMOUNTS.length - 1]
+  return { wordLengths, scaleFactorIndices: scaleFactorTable }
 }
 
 /**
- * Distribute available bits among BFUs using a greedy heap-based algorithm
- * Iteratively upgrades quantization precision for the BFU with highest SMR
- * @param {number} activeBfuCount - Number of BFUs to distribute bits to
- * @param {Float32Array} smrValues - Signal-to-Mask ratios for prioritization
- * @param {Array} bfuSizes - Size (coefficient count) of each BFU
- * @param {number} remainingBits - Total bits available for distribution
- * @returns {Int32Array} Word length index allocation per BFU
+ * Find the optimal scale factor index for a set of coefficients.
+ * Same semantics as the original.
+ * @param {Float32Array} coefficients
+ * @returns {number}
  */
-function distributeBitsGreedy(
-  activeBfuCount,
-  smrValues,
-  bfuSizes,
-  remainingBits
-) {
-  const wordLengthAllocation = new Int32Array(activeBfuCount)
-  const heapBfuIndices = []
-  const heapPriorities = []
-
-  // Initialize heap with BFUs that have finite SMR values
-  for (let bfuIndex = 0; bfuIndex < activeBfuCount; bfuIndex++) {
-    if (smrValues[bfuIndex] > -Infinity) {
-      heapBfuIndices.push(bfuIndex)
-      heapPriorities.push(smrValues[bfuIndex])
-    }
+export function findScaleFactor(coefficients) {
+  let maxAmplitude = 0.0
+  const n = coefficients.length | 0
+  let i = 0
+  const n4 = n & ~3
+  for (; i < n4; i += 4) {
+    const a0 = Math.abs(coefficients[i])
+    const a1 = Math.abs(coefficients[i + 1])
+    const a2 = Math.abs(coefficients[i + 2])
+    const a3 = Math.abs(coefficients[i + 3])
+    if (a0 > maxAmplitude) maxAmplitude = a0
+    if (a1 > maxAmplitude) maxAmplitude = a1
+    if (a2 > maxAmplitude) maxAmplitude = a2
+    if (a3 > maxAmplitude) maxAmplitude = a3
   }
-
-  // Build max-heap structure
-  for (
-    let nodeIndex = (heapBfuIndices.length >> 1) - 1;
-    nodeIndex >= 0;
-    nodeIndex--
-  ) {
-    siftDown(heapBfuIndices, heapPriorities, nodeIndex)
+  for (; i < n; i++) {
+    const a = Math.abs(coefficients[i])
+    if (a > maxAmplitude) maxAmplitude = a
   }
-
-  // Greedily allocate bits to highest priority BFUs
-  while (heapBfuIndices.length && remainingBits > 0) {
-    const currentBfu = heapBfuIndices[0]
-    const currentWordLength = wordLengthAllocation[currentBfu]
-
-    // Skip BFUs that have reached maximum quantization precision
-    if (currentWordLength >= MAX_WORD_LENGTH_INDEX) {
-      popRoot(heapBfuIndices, heapPriorities)
-      continue
-    }
-
-    // Calculate bit cost for upgrading this BFU's quantization
-    const bfuSize = bfuSizes[currentBfu]
-    const upgradeCost =
-      WORD_LENGTH_BITS[currentWordLength + 1] * bfuSize -
-      WORD_LENGTH_BITS[currentWordLength] * bfuSize
-
-    if (upgradeCost > remainingBits) {
-      popRoot(heapBfuIndices, heapPriorities)
-      continue
+  if (maxAmplitude === 0) return 0
+
+  // Binary search
+  let low = 0
+  let high = SCALE_FACTORS.length - 1
+  while (low < high) {
+    const mid = (low + high) >> 1
+    if (maxAmplitude <= SCALE_FACTORS[mid]) {
+      high = mid
+    } else {
+      low = mid + 1
     }
-
-    // Perform the upgrade
-    remainingBits -= upgradeCost
-    wordLengthAllocation[currentBfu] = currentWordLength + 1
-    heapPriorities[0] += DISTORTION_DELTA_DB[currentWordLength]
-    siftDown(heapBfuIndices, heapPriorities, 0)
   }
-
-  return wordLengthAllocation
+  return low
 }
 
 /**
- * Remove the root element from a max-heap and restore heap property
- * @param {Array} heapIndices - Array of BFU indices forming the heap
- * @param {Array} heapPriorities - Array of priority values corresponding to indices
+ * 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 lastIndex = heapIndices.length - 1
-  heapIndices[0] = heapIndices[lastIndex]
-  heapPriorities[0] = heapPriorities[lastIndex]
+  const last = heapIndices.length - 1
+  heapIndices[0] = heapIndices[last]
+  heapPriorities[0] = heapPriorities[last]
   heapIndices.pop()
   heapPriorities.pop()
   if (heapIndices.length) siftDown(heapIndices, heapPriorities, 0)
 }
 
 /**
- * Restore max-heap property by sifting an element down to its correct position
- * @param {Array} heapIndices - Array of BFU indices forming the heap
- * @param {Array} heapPriorities - Array of priority values corresponding to indices
- * @param {number} startIndex - Index of element to sift down
+ * Restores max-heap property by sifting an element down from a given position.
+ *
+ * This function maintains the heap invariant where parent nodes have higher
+ * priority values than their children. It compares the element at startIndex
+ * 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 {number} startIndex
  */
 function siftDown(heapIndices, heapPriorities, startIndex) {
   const heapSize = heapIndices.length
-  let currentIndex = startIndex
-  const originalIndexValue = heapIndices[currentIndex]
-  const originalPriorityValue = heapPriorities[currentIndex]
+  let i = startIndex
+  const idxVal = heapIndices[i]
+  const prVal = heapPriorities[i]
 
   while (true) {
-    const leftChildIndex = (currentIndex << 1) + 1
-    const rightChildIndex = leftChildIndex + 1
-    let maxIndex = currentIndex
-    let maxPriority = originalPriorityValue
-
-    // Check if left child has higher priority
-    if (
-      leftChildIndex < heapSize &&
-      heapPriorities[leftChildIndex] > maxPriority
-    ) {
-      maxIndex = leftChildIndex
-      maxPriority = heapPriorities[leftChildIndex]
+    const l = (i << 1) + 1
+    const r = l + 1
+    let maxI = i
+    let maxP = prVal
+
+    if (l < heapSize && heapPriorities[l] > maxP) {
+      maxI = l
+      maxP = heapPriorities[l]
     }
-
-    // Check if right child has higher priority
-    if (
-      rightChildIndex < heapSize &&
-      heapPriorities[rightChildIndex] > maxPriority
-    ) {
-      maxIndex = rightChildIndex
+    if (r < heapSize && heapPriorities[r] > maxP) {
+      maxI = r
     }
+    if (maxI === i) break
 
-    // If current position is correct, we're done
-    if (maxIndex === currentIndex) break
-
-    // Move the higher priority child up
-    heapIndices[currentIndex] = heapIndices[maxIndex]
-    heapPriorities[currentIndex] = heapPriorities[maxIndex]
-    currentIndex = maxIndex
+    heapIndices[i] = heapIndices[maxI]
+    heapPriorities[i] = heapPriorities[maxI]
+    i = maxI
   }
 
-  // Place original element in its final position
-  heapIndices[currentIndex] = originalIndexValue
-  heapPriorities[currentIndex] = originalPriorityValue
+  heapIndices[i] = idxVal
+  heapPriorities[i] = prVal
 }