carta1 1.1.6 → 1.1.8

package/bin/cli.js

@@ -82,6 +82,57 @@ function validateTitle(title) {
   return { valid: true }
 }
 
+/**
+ * Validate fixed block modes format and values
+ *
+ * @param {string} modes - Modes string in format "a,b,c"
+ * @returns {Object} Validation result
+ * @returns {boolean} returns.valid - Whether modes are valid
+ * @returns {Array<number>} [returns.modes] - Parsed modes if valid
+ * @returns {string} [returns.error] - Error message if invalid
+ */
+function validateModes(modes) {
+  if (!modes) {
+    return { valid: true }
+  }
+
+  const parts = modes.split(',')
+  if (parts.length !== 3) {
+    return {
+      valid: false,
+      error: `Modes must have exactly 3 values separated by commas, got ${parts.length}`,
+    }
+  }
+
+  const parsedModes = []
+  const validValues = [
+    [0, 2], // Position 1: 0 or 2
+    [0, 2], // Position 2: 0 or 2
+    [0, 3], // Position 3: 0 or 3
+  ]
+
+  for (let i = 0; i < 3; i++) {
+    const mode = parseInt(parts[i], 10)
+    if (isNaN(mode)) {
+      return {
+        valid: false,
+        error: `Mode at position ${i + 1} is not a number: "${parts[i]}"`,
+      }
+    }
+
+    if (!validValues[i].includes(mode)) {
+      return {
+        valid: false,
+        error: `Mode at position ${i + 1} must be ${validValues[i].join(' or ')}, got ${mode}`,
+      }
+    }
+
+    parsedModes.push(mode)
+  }
+
+  return { valid: true, modes: parsedModes }
+}
+
 /**
  * Progress tracking utility for encoding/decoding operations
  *
@@ -386,6 +437,16 @@ async function encodeFile(inputFile, outputFile, options) {
     }
   }
 
+  // Validate modes if provided
+  let fixedBlockModes = null
+  if (options.modes) {
+    const validation = validateModes(options.modes)
+    if (!validation.valid) {
+      throw new Error(validation.error)
+    }
+    fixedBlockModes = validation.modes
+  }
+
   if (!options.quiet) {
     const bitrate = Math.round((BITRATE_PER_CHANNEL * reader.channels) / 1000)
     console.log(
@@ -408,6 +469,9 @@ async function encodeFile(inputFile, outputFile, options) {
     if (options.bias !== undefined) {
       encoderOptions.setValue('allocationBias', options.bias)
     }
+    if (fixedBlockModes) {
+      encoderOptions.setValue('fixedBlockModes', fixedBlockModes)
+    }
 
     const encodedFrames = AudioProcessor.encodeStream(reader, {
       channelCount: reader.channels,
@@ -642,6 +706,10 @@ async function main() {
       'Bit allocation bias (default: 1.0)',
       parseFloat
     )
+    .option(
+      '-m, --modes <modes>',
+      'Fixed block modes [0/2],[0/2],[0/3] for low,mid,high bands (skips transient detection)'
+    )
     .argument('<input>', 'Input file path')
     .argument('<output>', 'Output file path')
     .parse()
@@ -693,3 +761,5 @@ main().catch((error) => {
   console.error(error.stack)
   process.exit(1)
 })
+
+export { validateModes }

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,58 +30,158 @@ import {
   WORD_LENGTH_BITS,
   INV_POWER_OF_TWO,
   SCALE_FACTORS,
+  BFU_AMOUNTS,
 } from '../core/constants.js'
 
 /**
- * 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
+ * @param {number} maxBfuCount The maximum BFU index to consider (e.g., from BFU_AMOUNTS)
  * @param {number} allocationBias
  * @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)
+
+  for (let i = 0; i < maxBfuCount; i++) {
+    const sz = bfuSizes[i] | 0
+    if (sz === 0) continue
+
+    const sfi = findScaleFactor(bfuData[i].subarray(0, sz))
+    allScaleFactorIndices[i] = sfi
+    if (sfi > 0) {
+      const scaleFactor = SCALE_FACTORS[sfi]
+      const effectiveScaleFactor = Math.pow(scaleFactor, allocationBias)
+      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,
+      allocationBias,
+      allScaleFactorIndices
+    )
+
+    const totalDistortion = calculateTotalDistortion(
+      candidateBfuCount,
+      maxBfuCount,
+      bfuSizes,
+      rdoResult.wordLengths,
+      rdoResult.scaleFactorIndices,
+      allocationBias,
+      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 - The number of BFUs that were coded.
+ * @param {number} maxBfuCount - The total number of BFUs considered.
+ * @param {Int32Array} bfuSizes - Sizes of each BFU.
+ * @param {Int32Array} wordLengths - The allocated word length for each active BFU.
+ * @param {Int32Array} scaleFactorIndices - The scale factor index for each BFU.
+ * @param {number} allocationBias - The RDO bias factor.
+ * @param {Float32Array} zeroBitDistortions - Pre-calculated distortion for uncoded bands.
+ * @returns {number} The total calculated distortion.
+ */
+function calculateTotalDistortion(
+  activeBfuCount,
+  maxBfuCount,
+  bfuSizes,
+  wordLengths,
+  scaleFactorIndices,
+  allocationBias,
+  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 scaleFactor = SCALE_FACTORS[sfi]
+    const effectiveScaleFactor = Math.pow(scaleFactor, allocationBias)
+    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 {Int32Array} allScaleFactorIndices - Pre-calculated SFIs for all potential BFUs.
  * @returns {{wordLengths: Int32Array, scaleFactorIndices: Int32Array}}
  */
 function distributeBitsRDO(
   activeBfuCount,
-  bfuData,
   bfuSizes,
   remainingBits,
-  allocationBias
+  allocationBias,
+  allScaleFactorIndices
 ) {
-  const scaleFactorTable = new Int32Array(NUM_BFUS)
+  const scaleFactorTable = allScaleFactorIndices
   const wordLengths = new Int32Array(activeBfuCount)
 
   const heapIndices = []
@@ -108,9 +207,7 @@ function distributeBitsRDO(
     const sz = bfuSizes[bfuIndex] | 0
     if (sz === 0) continue
 
-    const sfi = findScaleFactor(bfuData[bfuIndex].subarray(0, sz))
-    scaleFactorTable[bfuIndex] = sfi
-
+    const sfi = scaleFactorTable[bfuIndex]
     if (sfi === 0) continue
 
     const currentWl = 0

package/codec/core/options.js

@@ -19,6 +19,7 @@ class EncoderOptions {
       transientThresholdMid: 1.5,
       transientThresholdHigh: 2.0,
       allocationBias: 1.0,
+      fixedBlockModes: null,
     }
 
     this.metadata = {
@@ -54,6 +55,13 @@ class EncoderOptions {
         range: [0.5, 3.0],
         step: 0.01,
       },
+      fixedBlockModes: {
+        default: this.values.fixedBlockModes,
+        name: 'Fixed block modes',
+        description:
+          'Override transient detection and use fixed block modes. Format: [low, mid, high] where low/mid can be 0 or 2, high can be 0 or 3. When set, transient detection is skipped.',
+        type: 'array',
+      },
     }
 
     // Apply user-provided options
@@ -86,12 +94,15 @@ class EncoderOptions {
     }
 
     const meta = this.metadata[key]
-    const [min, max] = meta.range
 
-    if (value < min || value > max) {
-      throw new Error(
-        `Value for ${key} must be between ${min} and ${max}, got ${value}`
-      )
+    // Skip range validation for array types
+    if (meta.type !== 'array') {
+      const [min, max] = meta.range
+      if (value < min || value > max) {
+        throw new Error(
+          `Value for ${key} must be between ${min} and ${max}, got ${value}`
+        )
+      }
     }
 
     this.values[key] = value
@@ -126,6 +137,10 @@ class EncoderOptions {
     return this.values.allocationBias
   }
 
+  get fixedBlockModes() {
+    return this.values.fixedBlockModes
+  }
+
   getMetadata(key) {
     return this.metadata[key]
   }

package/codec/pipeline/encoder.js

@@ -125,17 +125,24 @@ export function blockSelectorStage(context) {
    */
   return (input) => {
     const { bands } = input
-    const fftSizes = [FFT_SIZE_LOW, FFT_SIZE_MID, FFT_SIZE_HIGH]
-    const blockModes = bands.map((bandSamples, bandIndex) => {
-      const coeffs = performFFT(bandSamples, fftSizes[bandIndex])
-      const transient = detectTransient(
-        coeffs,
-        bufferPool.transientDetection[bandIndex],
-        options.transientThresholdLow
-      )
-      bufferPool.transientDetection[bandIndex] = coeffs
-      return transient * Math.max(bandIndex + 1, 2)
-    })
+
+    // Use fixed block modes if provided, otherwise do transient detection
+    let blockModes
+    if (options.fixedBlockModes) {
+      blockModes = options.fixedBlockModes
+    } else {
+      const fftSizes = [FFT_SIZE_LOW, FFT_SIZE_MID, FFT_SIZE_HIGH]
+      blockModes = bands.map((bandSamples, bandIndex) => {
+        const coeffs = performFFT(bandSamples, fftSizes[bandIndex])
+        const transient = detectTransient(
+          coeffs,
+          bufferPool.transientDetection[bandIndex],
+          options.transientThresholdLow
+        )
+        bufferPool.transientDetection[bandIndex] = coeffs
+        return transient * Math.max(bandIndex + 1, 2)
+      })
+    }
 
     return {
       bands,
@@ -385,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)
@@ -397,8 +409,8 @@ export function quantizationStage(context) {
 
     return {
       nBfu: selectedBfuCount,
-      scaleFactorIndices,
-      wordLengthIndices: allocation.slice(0, selectedBfuCount),
+      scaleFactorIndices: slicedScaleFactorIndices,
+      wordLengthIndices: slicedWordLengthIndices,
       quantizedCoefficients,
       blockModes,
     }