carta1 1.0.21 → 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,373 +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,
-  NUM_BFUS,
-  SAMPLE_RATE,
-  BFU_FREQUENCIES,
-  BFU_AMOUNTS_COUNT,
-  PSYMODEL_MIN_POWER_DB,
-  PSYMODEL_CB_FREQ_INDICES,
-  INTERPOLATION_COMPENSATION_FACTOR,
-  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) {
-  // Calculate signal energy for each BFU
-  const signalEnergyDb = calculateBfuEnergy(bfuData, bfuSizes, maxBfuCount)
-
-  // Interpolate critical band thresholds to BFUs
-  const maskThresholdDb = interpolateCriticalBandsToBfus(
-    psychoResults.criticalBandThresholds
-  )
-
-  // Calculate Signal-to-Mask Ratios
-  const smrValues = calculateSMR(signalEnergyDb, maskThresholdDb, maxBfuCount)
-
-  // Determine optimal number of BFUs to use
-  const actualBfuCount = selectOptimalBfuCount(
-    smrValues,
-    signalEnergyDb,
-    maxBfuCount
-  )
-
-  // Calculate available bits for allocation
-  const availableBits =
-    FRAME_BITS - FRAME_OVERHEAD_BITS - actualBfuCount * BITS_PER_BFU_METADATA
+export function allocateBits(bfuData, bfuSizes, maxBfuCount) {
+  const usedBFU = maxBfuCount
+  const avail =
+    FRAME_BITS - FRAME_OVERHEAD_BITS - usedBFU * BITS_PER_BFU_METADATA
 
-  // Perform actual bit allocation
-  const allocation = performBitAllocation(
-    actualBfuCount,
-    smrValues,
-    bfuSizes,
-    availableBits
-  )
+  const rdoResult = distributeBitsRDO(usedBFU, bfuData, bfuSizes, avail)
 
   return {
-    bfuCount: actualBfuCount,
-    allocation,
+    bfuCount: usedBFU,
+    allocation: rdoResult.wordLengths,
+    scaleFactorIndices: rdoResult.scaleFactorIndices,
   }
 }
 
 /**
- * Calculate energy in dB for each BFU
- * @param {Array} bfuData - BFU coefficient data
- * @param {Array} bfuSizes - Size of each BFU
- * @param {number} bfuCount - Number of BFUs to process
- * @returns {Float32Array} Energy values in dB
+ * 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 calculateBfuEnergy(bfuData, bfuSizes, bfuCount) {
-  const energyPerBfu = new Float32Array(bfuCount)
-
-  for (let i = 0; i < bfuCount; i++) {
-    const data = bfuData[i]
-    const size = bfuSizes[i]
-
-    if (size === 0) {
-      energyPerBfu[i] = PSYMODEL_MIN_POWER_DB
-      continue
-    }
-
-    // Calculate mean square energy
-    let energy = 0
-    for (let j = 0; j < size; j++) {
-      energy += data[j] * data[j]
+function distributeBitsRDO(activeBfuCount, bfuData, bfuSizes, remainingBits) {
+  const scaleFactorTable = new Int32Array(NUM_BFUS)
+  const wordLengths = new Int32Array(activeBfuCount)
+
+  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
     }
-
-    // Convert to dB correctly using log10
-    energyPerBfu[i] =
-      energy > 0 ? 10 * Math.log10(energy / size) : PSYMODEL_MIN_POWER_DB
   }
 
-  return energyPerBfu
-}
+  const heapIndices = []
+  const heapPriorities = []
+  const deltaDist = (bfuIndex, currentWl, nextWl) => {
+    const base = baseWeight[bfuIndex]
+    if (base === 0) return 0
 
-/**
- * Interpolate critical band thresholds directly to BFU frequencies
- * @param {Float32Array} criticalBandThresholds - Critical band thresholds
- * @returns {Float32Array} Masking threshold per BFU
- */
-function interpolateCriticalBandsToBfus(criticalBandThresholds) {
-  const maskThresholdPerBfu = new Float32Array(NUM_BFUS)
-  const freqPerBin = SAMPLE_RATE / PSYMODEL_FFT_SIZE
-
-  for (let i = 0; i < NUM_BFUS; i++) {
-    const bfuFreq = BFU_FREQUENCIES[i]
-    const fftBinIndex = Math.round(bfuFreq / freqPerBin)
-
-    // Find which critical bands surround this FFT bin
-    let bandIndex = 0
-    while (
-      bandIndex < PSYMODEL_CB_FREQ_INDICES.length - 1 &&
-      PSYMODEL_CB_FREQ_INDICES[bandIndex + 1] < fftBinIndex
-    ) {
-      bandIndex++
-    }
+    const bits1 = WORD_LENGTH_BITS[currentWl] | 0
+    const bits2 = WORD_LENGTH_BITS[nextWl] | 0
 
-    if (fftBinIndex <= PSYMODEL_CB_FREQ_INDICES[0]) {
-      maskThresholdPerBfu[i] = criticalBandThresholds[0]
-    } else if (
-      fftBinIndex >=
-      PSYMODEL_CB_FREQ_INDICES[PSYMODEL_CB_FREQ_INDICES.length - 1]
-    ) {
-      maskThresholdPerBfu[i] =
-        criticalBandThresholds[criticalBandThresholds.length - 1]
-    } else {
-      const x0 = PSYMODEL_CB_FREQ_INDICES[bandIndex]
-      const x1 = PSYMODEL_CB_FREQ_INDICES[bandIndex + 1]
-      const y0 = criticalBandThresholds[bandIndex]
-      const y1 = criticalBandThresholds[bandIndex + 1]
-      const bandWidth = x1 - x0
+    const f1 = bits1 === 0 ? POW2_POS_P : POW2_NEG_P[bits1]
+    const f2 = POW2_NEG_P[bits2]
 
-      if (bandWidth > 0) {
-        const t = (fftBinIndex - x0) / bandWidth
-        const interpolated = y0 + (y1 - y0) * t
-        const compensation =
-          Math.abs(y1 - y0) * INTERPOLATION_COMPENSATION_FACTOR
-        maskThresholdPerBfu[i] = interpolated + compensation
-      } else {
-        maskThresholdPerBfu[i] = y0
-      }
-    }
+    return base * (f1 - f2)
   }
 
-  return maskThresholdPerBfu
-}
+  for (let bfuIndex = 0; bfuIndex < activeBfuCount; bfuIndex++) {
+    const sz = bfuSizes[bfuIndex] | 0
+    if (sz === 0) continue
+    if (scaleFactorTable[bfuIndex] === 0) continue
 
-/**
- * Calculate Signal-to-Mask Ratio for each BFU
- * @param {Float32Array} signalEnergyDb - Signal energy per BFU
- * @param {Float32Array} maskThresholdDb - Masking threshold per BFU
- * @param {number} maxBfuCount - Maximum number of BFUs
- * @returns {Float32Array} SMR values in dB
- */
-function calculateSMR(signalEnergyDb, maskThresholdDb, maxBfuCount) {
-  const smrValues = new Float32Array(maxBfuCount)
+    const currentWl = 0
+    const nextWl = 1
+    const deltaBits =
+      (WORD_LENGTH_BITS[nextWl] - WORD_LENGTH_BITS[currentWl]) | 0
+    if (deltaBits <= 0) continue
 
-  for (let bfu = 0; bfu < maxBfuCount; bfu++) {
-    smrValues[bfu] =
-      signalEnergyDb[bfu] <= PSYMODEL_MIN_POWER_DB
-        ? -Infinity
-        : signalEnergyDb[bfu] - maskThresholdDb[bfu]
-  }
+    const deltaCost = deltaBits * sz
+    const dd = deltaDist(bfuIndex, currentWl, nextWl)
 
-  return smrValues
-}
+    heapIndices.push(bfuIndex)
+    heapPriorities.push(dd / deltaCost) // priority = ΔD / ΔR
+  }
 
-/**
- * Select optimal number of BFUs to use based on SMR distribution
- * @param {Float32Array} smrValues - Signal-to-Mask ratios
- * @param {Float32Array} signalEnergyDb - Signal energy per BFU
- * @param {number} maxBfuCount - Maximum available BFUs
- * @returns {number} Optimal BFU count
- */
-function selectOptimalBfuCount(smrValues, signalEnergyDb, maxBfuCount) {
-  // Check if we have any audible content (positive SMR)
-  const hasAudibleContent = smrValues.some((smr) => smr > 0)
+  // Heapify
+  for (let i = (heapIndices.length >> 1) - 1; i >= 0; i--)
+    siftDown(heapIndices, heapPriorities, i)
 
-  if (hasAudibleContent) {
-    // Create sorted list of BFUs by their contribution (positive SMR only)
-    const contributions = []
-    for (let i = 0; i < maxBfuCount; i++) {
-      if (smrValues[i] > 0) {
-        contributions.push({ index: i, smr: smrValues[i] })
-      }
-    }
-    contributions.sort((a, b) => b.smr - a.smr)
+  // Greedy spending
+  while (remainingBits > 0 && heapIndices.length > 0) {
+    const bfu = heapIndices[0]
+    const cur = wordLengths[bfu] | 0
+    const nxt = cur + 1
 
-    if (contributions.length === 0) {
-      return BFU_AMOUNTS[BFU_AMOUNTS.length - 1]
-    }
+    const sz = bfuSizes[bfu] | 0
+    const deltaBits = (WORD_LENGTH_BITS[nxt] - WORD_LENGTH_BITS[cur]) | 0
+    const cost = deltaBits * sz
 
-    // Find the natural cutoff using gradient of cumulative SMR
-    const cumulativeSMR = []
-    let sum = 0
-    for (let i = 0; i < contributions.length; i++) {
-      sum += contributions[i].smr
-      cumulativeSMR.push(sum)
+    if (cost > remainingBits || cost <= 0) {
+      popRoot(heapIndices, heapPriorities)
+      continue
     }
 
-    // Find where the gradient becomes shallow (diminishing returns)
-    for (const candidateCount of BFU_AMOUNTS) {
-      if (candidateCount > maxBfuCount) continue
-
-      // Check if all significant contributions fit within this count
-      const requiredBfus = contributions
-        .slice(0, Math.min(contributions.length, candidateCount))
-        .map((c) => c.index)
-
-      const maxRequiredIndex = Math.max(...requiredBfus, 0)
+    remainingBits -= cost
+    wordLengths[bfu] = nxt
 
-      if (maxRequiredIndex < candidateCount) {
-        // Check if we've captured the bulk of the contribution
-        const capturedIndex = Math.min(
-          candidateCount - 1,
-          contributions.length - 1
-        )
-        if (capturedIndex >= contributions.length - 1) {
-          return candidateCount
-        }
-
-        // Use gradient to detect diminishing returns
-        const remainingIndices = contributions.length - capturedIndex - 1
-        if (remainingIndices > 0) {
-          const avgRemaining =
-            (cumulativeSMR[cumulativeSMR.length - 1] -
-              cumulativeSMR[capturedIndex]) /
-            remainingIndices
-          const avgCaptured = cumulativeSMR[capturedIndex] / (capturedIndex + 1)
-
-          // If remaining BFUs contribute much less on average, we've found our cutoff
-          if (avgRemaining < avgCaptured * 0.1) {
-            return candidateCount
-          }
-        }
-      }
-    }
-  } else {
-    // Find the highest BFU index that contains actual signal
-    let highestSignalBfu = -1
-    for (let i = maxBfuCount - 1; i >= 0; i--) {
-      if (
-        signalEnergyDb[i] > PSYMODEL_MIN_POWER_DB &&
-        smrValues[i] > -Infinity
-      ) {
-        highestSignalBfu = i
-        break
-      }
-    }
-
-    // Find smallest BFU count that includes all signal
-    for (const candidateCount of BFU_AMOUNTS) {
-      if (candidateCount > highestSignalBfu) {
-        return candidateCount
+    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_COUNT - 1]
+  return { wordLengths, scaleFactorIndices: scaleFactorTable }
 }
 
 /**
- * Allocate available bits among BFUs using a greedy algorithm
- * @param {number} actualBfuCount - Number of BFUs to allocate
- * @param {Float32Array} smrValues - Signal-to-Mask ratios
- * @param {Array} bfuSizes - Size of each BFU
- * @param {number} availableBits - Total bits available for allocation
- * @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 performBitAllocation(
-  actualBfuCount,
-  smrValues,
-  bfuSizes,
-  availableBits
-) {
-  const allocation = new Int32Array(actualBfuCount)
-  const heap = []
-
-  // Initialize heap with BFUs that have signal
-  for (let i = 0; i < actualBfuCount; i++) {
-    if (smrValues[i] > -Infinity) {
-      heap.push({ bfu: i, priority: smrValues[i] })
-    }
+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
-  for (let i = Math.floor(heap.length / 2) - 1; i >= 0; i--) {
-    heapifyDown(heap, i)
+  for (; i < n; i++) {
+    const a = Math.abs(coefficients[i])
+    if (a > maxAmplitude) maxAmplitude = a
   }
-
-  // Greedy allocation
-  while (heap.length > 0 && availableBits > 0) {
-    const bestBfu = heap[0]
-    const currentWl = allocation[bestBfu.bfu]
-
-    if (currentWl >= MAX_WORD_LENGTH_INDEX) {
-      heap[0] = heap[heap.length - 1]
-      heap.pop()
-      if (heap.length > 0) heapifyDown(heap, 0)
-      continue
-    }
-
-    const upgradeCost = calculateUpgradeCost(bestBfu.bfu, currentWl, bfuSizes)
-
-    if (upgradeCost <= availableBits) {
-      availableBits -= upgradeCost
-      allocation[bestBfu.bfu]++
-      bestBfu.priority += DISTORTION_DELTA_DB[currentWl]
-      heapifyDown(heap, 0)
+  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 {
-      heap[0] = heap[heap.length - 1]
-      heap.pop()
-      if (heap.length > 0) heapifyDown(heap, 0)
+      low = mid + 1
     }
   }
-
-  return allocation
+  return low
 }
 
 /**
- * Calculate bit cost to upgrade a BFU's word length
- * @param {number} bfuIndex - Index of the BFU to upgrade
- * @param {number} currentWl - Current word length of the BFU
- * @param {number[]} bfuSizes - Array of BFU sizes (number of coefficients per BFU)
- * @returns {number} Additional bits required to upgrade word length by 1
+ * 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 calculateUpgradeCost(bfuIndex, currentWl, bfuSizes) {
-  const currentBits = WORD_LENGTH_BITS[currentWl] * bfuSizes[bfuIndex]
-  const nextBits = WORD_LENGTH_BITS[currentWl + 1] * bfuSizes[bfuIndex]
-  return nextBits - currentBits
+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)
 }
 
 /**
- * Maintain max heap property by moving element down
- * @param {Array} heap - Heap array
- * @param {number} startIdx - Starting index
+ * 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 heapifyDown(heap, startIdx) {
-  const length = heap.length
-  const element = heap[startIdx]
+function siftDown(heapIndices, heapPriorities, startIndex) {
+  const heapSize = heapIndices.length
+  let i = startIndex
+  const idxVal = heapIndices[i]
+  const prVal = heapPriorities[i]
 
   while (true) {
-    const leftChild = 2 * startIdx + 1
-    const rightChild = 2 * startIdx + 2
-    let largest = startIdx
-    let largestPriority = element.priority
-
-    if (leftChild < length && heap[leftChild].priority > largestPriority) {
-      largest = leftChild
-      largestPriority = heap[leftChild].priority
+    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]
     }
-
-    if (rightChild < length && heap[rightChild].priority > largestPriority) {
-      largest = rightChild
+    if (r < heapSize && heapPriorities[r] > maxP) {
+      maxI = r
     }
+    if (maxI === i) break
 
-    if (largest === startIdx) break
-
-    heap[startIdx] = heap[largest]
-    startIdx = largest
+    heapIndices[i] = heapIndices[maxI]
+    heapPriorities[i] = heapPriorities[maxI]
+    i = maxI
   }
 
-  heap[startIdx] = element
+  heapIndices[i] = idxVal
+  heapPriorities[i] = prVal
 }