carta1 1.1.10 → 1.3.0

package/bin/cli.js

@@ -19,9 +19,10 @@ import { performance } from 'perf_hooks'
 import cliProgress from 'cli-progress'
 import wav from 'wav'
 
-import { AudioProcessor } from '../codec/io/processor.js'
-import { AeaReader } from '../codec/io/readers.js'
-import { deserializeFrame, AeaFile } from '../codec/io/serialization.js'
+import { AudioProcessor } from '../codec/boundary/processor.js'
+import { AeaReader } from '../codec/boundary/reader.js'
+import { AeaFile } from '../codec/boundary/container.js'
+import { deserializeFrame } from '../codec/syntax/frame.js'
 import { EncoderOptions } from '../codec/core/options.js'
 import {
   SAMPLE_RATE,
@@ -483,6 +484,7 @@ async function encodeFile(inputFile, outputFile, options) {
     const blob = await AudioProcessor.createAeaBlob(encodedFrames, {
       title,
       channelCount: reader.channels,
+      sampleCount: reader.totalSamples,
     })
 
     const buffer = await blob.arrayBuffer()
@@ -533,11 +535,13 @@ async function decodeFile(inputFile, outputFile, options) {
 
     const decodedFrames = AudioProcessor.decodeStream(reader, {
       channelCount: metadata.channelCount,
+      primingSampleCount: metadata.primingSampleCount,
+      sampleCount: metadata.sampleCount,
       onProgress,
     })
 
     const pcmFrames = await AudioProcessor.collectFrames(decodedFrames)
-    const wavBlob = AudioProcessor.createWavBlob(
+    const wavBlob = AudioProcessor.createPcmWaveBlob(
       pcmFrames,
       metadata.channelCount,
       SAMPLE_RATE

package/codec/{coding/bitallocation.js → allocation/solve.js}

@@ -27,13 +27,15 @@ import {
   FRAME_OVERHEAD_BITS,
   BITS_PER_BFU_METADATA,
   MAX_WORD_LENGTH_INDEX,
+} from '../core/constants.js'
+import {
   WORD_LENGTH_BITS,
   INV_POWER_OF_TWO,
   SCALE_FACTORS,
   BFU_AMOUNTS,
   WORD_LENGTH_DELTA_BITS,
   DISTORTION_DELTA_FACTORS,
-} from '../core/constants.js'
+} from '../core/tables.js'
 
 const biasedScaleFactorCache = new Map()
 
@@ -61,84 +63,43 @@ function buildBiasedScaleFactorTable(bias) {
 }
 
 /**
- * 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.
+ * Evaluate one legal active-BFU count.
  *
- * @param {Array<Float32Array>} bfuData
- * @param {Int32Array} bfuSizes
+ * @param {number} activeBfuCount
  * @param {number} maxBfuCount
- * @param {number} allocationBias
- * @returns {{bfuCount:number, allocation:Int32Array, scaleFactorIndices:Int32Array}}
+ * @param {Int32Array} bfuSizes
+ * @param {number} remainingBits
+ * @param {Float64Array} biasedScaleFactors
+ * @param {Int32Array} allScaleFactorIndices
+ * @param {Float32Array} zeroBitDistortions
+ * @returns {object} Allocation result.
  */
-export function allocateBits(bfuData, bfuSizes, maxBfuCount, allocationBias) {
-  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
+function search(
+  activeBfuCount,
+  maxBfuCount,
+  bfuSizes,
+  remainingBits,
+  biasedScaleFactors,
+  allScaleFactorIndices,
+  zeroBitDistortions
+) {
+  const allocation = distributeBits(
+    activeBfuCount,
+    bfuSizes,
+    remainingBits,
+    biasedScaleFactors,
+    allScaleFactorIndices
+  )
+  const distortion = measureDistortion(
+    activeBfuCount,
+    maxBfuCount,
+    bfuSizes,
+    allocation.wordLengths,
+    allocation.scaleFactorIndices,
+    biasedScaleFactors,
+    zeroBitDistortions
+  )
+  return { distortion, ...allocation }
 }
 
 /**
@@ -154,7 +115,7 @@ export function allocateBits(bfuData, bfuSizes, maxBfuCount, allocationBias) {
  * @param {Float32Array} zeroBitDistortions
  * @returns {number}
  */
-function calculateTotalDistortion(
+function measureDistortion(
   activeBfuCount,
   maxBfuCount,
   bfuSizes,
@@ -198,9 +159,9 @@ function calculateTotalDistortion(
  * @param {number} remainingBits
  * @param {Float64Array} biasedScaleFactors
  * @param {Int32Array} allScaleFactorIndices
- * @returns {{wordLengths: Int32Array, scaleFactorIndices: Int32Array}}
+ * @returns {object} Retained allocation decisions.
  */
-function distributeBitsRDO(
+function distributeBits(
   activeBfuCount,
   bfuSizes,
   remainingBits,
@@ -280,24 +241,6 @@ function distributeBitsRDO(
   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, length) {
-  let maxAmplitude = 0.0
-  for (let i = 0; i < length; i++) {
-    const a = Math.abs(coefficients[i])
-    if (a > maxAmplitude) maxAmplitude = a
-  }
-  if (maxAmplitude === 0) return 0
-  const index = Math.ceil(3 * (Math.log2(maxAmplitude) + 21))
-  return Math.max(0, Math.min(63, index))
-}
-
 /**
  * Restores max-heap property by sifting an element down from a given position.
  *
@@ -339,3 +282,94 @@ function siftDown(heapIndices, heapPriorities, startIndex, heapSize) {
   heapIndices[i] = idxVal
   heapPriorities[i] = prVal
 }
+
+/**
+ * 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} allocationBias
+ * @returns {{bfuCount:number, allocation:Int32Array, scaleFactorIndices:Int32Array}}
+ */
+export function solve(bfuData, bfuSizes, maxBfuCount, allocationBias) {
+  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 result = search(
+      candidateBfuCount,
+      maxBfuCount,
+      bfuSizes,
+      availableBits,
+      biasedScaleFactors,
+      allScaleFactorIndices,
+      zeroBitDistortions
+    )
+
+    if (result.distortion < minTotalDistortion) {
+      minTotalDistortion = result.distortion
+      bestResult = {
+        bfuCount: candidateBfuCount,
+        allocation: result.wordLengths,
+        scaleFactorIndices: result.scaleFactorIndices,
+      }
+    }
+  }
+
+  if (!bestResult) {
+    const fallbackBfuCount = BFU_AMOUNTS[0]
+    return {
+      bfuCount: fallbackBfuCount,
+      allocation: new Int32Array(fallbackBfuCount),
+      scaleFactorIndices: new Int32Array(NUM_BFUS),
+    }
+  }
+
+  return bestResult
+}
+
+/**
+ * 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, length) {
+  let maxAmplitude = 0.0
+  for (let i = 0; i < length; i++) {
+    const a = Math.abs(coefficients[i])
+    if (a > maxAmplitude) maxAmplitude = a
+  }
+  if (maxAmplitude === 0) return 0
+  const index = Math.ceil(3 * (Math.log2(maxAmplitude) + 21))
+  return Math.max(0, Math.min(63, index))
+}

package/codec/allocation/source.js

@@ -0,0 +1,69 @@
+/**
+ * Carta1 allocation-source preparation.
+ */
+
+import {
+  BFU_BAND_BOUNDARIES,
+  BFU_START_LONG,
+  BFU_START_SHORT,
+  SPECS_PER_BFU,
+} from '../core/tables.js'
+
+/**
+ * Group spectral coefficients into block floating units.
+ *
+ * @param {Float32Array} coefficients
+ * @param {Array<number>} blockModes
+ * @returns {object} Grouped bit-frequency units.
+ */
+export function groupIntoBFUs(coefficients, blockModes) {
+  const bfuData = []
+  const bfuSizes = []
+  let coeffIndex = 0
+  let bfuIndex = 0
+
+  for (let band = 0; band < 3; band++) {
+    const bandStart = coeffIndex
+    const bandSize = band === 2 ? 256 : 128
+    const bandEnd = band < 2 ? BFU_BAND_BOUNDARIES[band] : SPECS_PER_BFU.length
+    const startPositions =
+      blockModes[band] === 0 ? BFU_START_LONG : BFU_START_SHORT
+
+    while (bfuIndex < bandEnd) {
+      const size = SPECS_PER_BFU[bfuIndex]
+      const startPos = startPositions[bfuIndex] - bandStart
+      const endPos = startPos + size
+      const bfu = new Float32Array(size)
+
+      if (startPos >= 0 && endPos <= bandSize) {
+        bfu.set(coefficients.subarray(bandStart + startPos, bandStart + endPos))
+      } else if (startPos < bandSize && endPos > 0) {
+        const srcStart = Math.max(0, startPos)
+        const srcEnd = Math.min(bandSize, endPos)
+        bfu.set(
+          coefficients.subarray(bandStart + srcStart, bandStart + srcEnd),
+          Math.max(0, -startPos)
+        )
+      }
+
+      bfuData.push(bfu)
+      bfuSizes.push(size)
+      bfuIndex++
+    }
+
+    coeffIndex += bandSize
+  }
+
+  return { bfuData, bfuSizes, bfuCount: bfuIndex }
+}
+
+/**
+ * Prepare the spectrum as an allocation source.
+ *
+ * @param {Float32Array} coefficients
+ * @param {Array<number>} blockModes
+ * @returns {object} Allocation source.
+ */
+export function prepare(coefficients, blockModes) {
+  return groupIntoBFUs(coefficients, blockModes)
+}

package/codec/allocation/stage.js

@@ -0,0 +1,38 @@
+/**
+ * Carta1 allocation stage.
+ */
+
+import { throwError } from '../utils.js'
+import { prepare } from './source.js'
+import { solve } from './solve.js'
+
+/**
+ * Allocate the frame budget across block floating units.
+ *
+ * @param {object} context
+ * @returns {Function}
+ */
+export function allocate(context) {
+  const options =
+    context?.options ?? throwError('allocate: options is required')
+
+  /**
+   * @param {object} input
+   * @returns {object}
+   */
+  return (input) => {
+    const { coefficients, blockModes } = input
+    const { bfuData, bfuSizes, bfuCount } = prepare(coefficients, blockModes)
+    const result = solve(bfuData, bfuSizes, bfuCount, options.allocationBias)
+    const nBfu = result.bfuCount
+
+    return {
+      bfuData,
+      bfuSizes,
+      nBfu,
+      scaleFactorIndices: result.scaleFactorIndices.slice(0, nBfu),
+      wordLengthIndices: result.allocation.slice(0, nBfu),
+      blockModes,
+    }
+  }
+}

package/codec/analysis/bands.js

@@ -0,0 +1,68 @@
+/**
+ * Carta1 QMF analysis application.
+ */
+
+import { QMF_ANALYSIS_DELAY_SAMPLES } from '../core/constants.js'
+import { analyzeQmf } from '../signal/qmf.js'
+import { throwError } from '../utils.js'
+
+/**
+ * Split one sample row through a two-band configurable QMF stage.
+ *
+ * @param {Float32Array} input
+ * @param {Float32Array} delay
+ * @param {object} scratch
+ * @returns {Float32Array[]}
+ */
+function analyzePair(input, delay, scratch) {
+  const window =
+    scratch.analysisWindows[input.length] ??
+    throwError(`QMF analysis window for ${input.length} samples is required`)
+  window.set(delay)
+  window.set(input, delay.length)
+
+  const sampleCount = input.length / 2
+  const bands = [new Float32Array(sampleCount), new Float32Array(sampleCount)]
+  analyzeQmf(window, bands, scratch)
+  delay.set(
+    window.subarray(input.length, input.length + QMF_ANALYSIS_DELAY_SAMPLES)
+  )
+  return bands
+}
+
+/**
+ * Split PCM into the three ATRAC1 frequency bands.
+ *
+ * @param {object} context
+ * @returns {Function}
+ * @throws {Error} If the buffer pool is missing
+ */
+export function analyzeBands(context) {
+  const bufferPool =
+    context?.bufferPool ?? throwError('analyzeBands: bufferPool is required')
+  const delays = bufferPool.qmfAnalysisDelays
+  const scratch = bufferPool.qmfScratch
+
+  /**
+   * @param {Float32Array} pcmSamples
+   * @returns {object}
+   */
+  return (pcmSamples) => {
+    const stage1 = analyzePair(pcmSamples, delays.lowBand, scratch)
+    const stage2 = analyzePair(stage1[0], delays.midBand, scratch)
+
+    const delayedHigh = scratch.highBandWindows[stage1[1].length]
+    delayedHigh.set(bufferPool.qmfHighBandDelay)
+    delayedHigh.set(stage1[1], bufferPool.qmfHighBandDelay.length)
+
+    const highBand = delayedHigh.slice(0, stage1[1].length)
+    bufferPool.qmfHighBandDelay.set(
+      delayedHigh.subarray(
+        stage1[1].length,
+        stage1[1].length + bufferPool.qmfHighBandDelay.length
+      )
+    )
+
+    return { bands: [stage2[0], stage2[1], highBand] }
+  }
+}

package/codec/analysis/{transient.js → blocks.js}

@@ -6,53 +6,9 @@
  * characteristics that require special handling during encoding.
  */
 
-import { FFT } from '../transforms/fft.js'
-
-/**
- * Perform FFT on time-domain samples and return magnitude spectrum
- * @param {Float32Array} samples - Time-domain samples
- * @param {number} fftSize - FFT size (must be power of 2)
- * @returns {Float32Array} Magnitude spectrum (positive frequencies only)
- */
-export function performFFT(samples, fftSize) {
-  const real = new Float32Array(fftSize)
-  const imag = new Float32Array(fftSize)
-
-  // Copy samples with zero-padding if necessary
-  const copyLen = Math.min(samples.length, fftSize)
-  real.set(samples.subarray(0, copyLen))
-
-  // Perform FFT
-  FFT.fft(real, imag)
-
-  // Calculate magnitude spectrum for positive frequencies
-  const magnitude = new Float32Array(fftSize / 2)
-  for (let i = 0; i < fftSize / 2; i++) {
-    magnitude[i] = Math.sqrt(real[i] * real[i] + imag[i] * imag[i])
-  }
-
-  return magnitude
-}
-
-/**
- * Detect transients by analyzing spectral changes between frames
- * @param {Float32Array} currentCoeffs - Current frame coefficients
- * @param {Float32Array} prevCoeffs - Previous frame coefficients
- * @param {number} threshold - Detection threshold
- * @returns {boolean} True if transient detected
- */
-export function detectTransient(currentCoeffs, prevCoeffs, threshold) {
-  // Can't detect transients without previous frame
-  if (!prevCoeffs) return false
-
-  // Calculate all spectral features
-  const features = calculateSpectralFeatures(currentCoeffs, prevCoeffs)
-
-  // Combine features using perceptually-motivated weighting
-  const transientScore = calculateTransientScore(features)
-
-  return transientScore > threshold
-}
+import { FFT_SIZE_HIGH, FFT_SIZE_LOW, FFT_SIZE_MID } from '../core/constants.js'
+import { FFT } from '../signal/fft.js'
+import { throwError } from '../utils.js'
 
 /**
  * Calculate all spectral features for transient detection
@@ -224,3 +180,90 @@ function calculateTransientScore(features) {
     4
   )
 }
+
+/**
+ * Perform FFT on time-domain samples and return magnitude spectrum
+ * @param {Float32Array} samples - Time-domain samples
+ * @param {number} fftSize - FFT size (must be power of 2)
+ * @returns {Float32Array} Magnitude spectrum (positive frequencies only)
+ */
+export function performFFT(samples, fftSize) {
+  const real = new Float32Array(fftSize)
+  const imag = new Float32Array(fftSize)
+
+  // Copy samples with zero-padding if necessary
+  const copyLen = Math.min(samples.length, fftSize)
+  real.set(samples.subarray(0, copyLen))
+
+  // Perform FFT
+  FFT.transform(real, imag)
+
+  // Calculate magnitude spectrum for positive frequencies
+  const magnitude = new Float32Array(fftSize / 2)
+  for (let i = 0; i < fftSize / 2; i++) {
+    magnitude[i] = Math.sqrt(real[i] * real[i] + imag[i] * imag[i])
+  }
+
+  return magnitude
+}
+
+/**
+ * Detect transients by analyzing spectral changes between frames
+ * @param {Float32Array} currentCoeffs - Current frame coefficients
+ * @param {Float32Array} prevCoeffs - Previous frame coefficients
+ * @param {number} threshold - Detection threshold
+ * @returns {boolean} True if transient detected
+ */
+export function detectTransient(currentCoeffs, prevCoeffs, threshold) {
+  // Can't detect transients without previous frame
+  if (!prevCoeffs) return false
+
+  // Calculate all spectral features
+  const features = calculateSpectralFeatures(currentCoeffs, prevCoeffs)
+
+  // Combine features using perceptually-motivated weighting
+  const transientScore = calculateTransientScore(features)
+
+  return transientScore > threshold
+}
+
+/**
+ * Select transform block sizes from transient analysis.
+ *
+ * @param {object} context
+ * @returns {Function}
+ * @throws {Error} If the required context is missing
+ */
+export function selectBlocks(context) {
+  const bufferPool =
+    context?.bufferPool ?? throwError('selectBlocks: bufferPool is required')
+  const options =
+    context?.options ?? throwError('selectBlocks: options is required')
+  const fftSizes = [FFT_SIZE_LOW, FFT_SIZE_MID, FFT_SIZE_HIGH]
+
+  /**
+   * @param {object} input
+   * @returns {object}
+   */
+  return (input) => {
+    const { bands } = input
+    let blockModes
+
+    if (options.fixedBlockModes) {
+      blockModes = options.fixedBlockModes
+    } else {
+      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, blockModes }
+  }
+}