carta1 1.1.9 → 1.2.0

package/codec/pipeline/encoder.js

@@ -1,450 +1,28 @@
 /**
  * Carta1 Audio Codec - Encoding Pipeline
  *
- * The encoding pipeline transforms PCM audio samples into ATRAC1 compressed format
- * through a series of processing stages:
- *
- * 1. QMF Analysis: Splits audio into frequency bands using quadrature mirror filters
- * 2. Block Selection: Detects transients to choose appropriate transform block sizes
- * 3. MDCT Transform: Applies Modified Discrete Cosine Transform to frequency bands
- * 4. Quantization: Performs psychoacoustic analysis, bit allocation, and quantization
- *
- * Each stage is implemented as a functional pipeline component that can be composed
- * using the pipe utility. The pipeline maintains state through a shared context
- * containing buffer pools and encoding options.
+ * The frame pipeline reads as analysis, allocation, then quantization. Byte
+ * packing remains the responsibility of serializeFrame().
  */
 
-import {
-  pipe,
-  throwError,
-  reverseSpectrum,
-  calculateBandOffset,
-} from '../utils.js'
-import { qmfAnalysis } from '../transforms/qmf.js'
-import { mdct64, mdct256, mdct512 } from '../transforms/mdct.js'
-import { groupIntoBFUs, quantize } from '../coding/quantization.js'
-import { allocateBits } from '../coding/bitallocation.js'
-import { BufferPool } from '../core/buffers.js'
+import { allocate } from '../allocation/stage.js'
+import { analyze } from '../analysis/stage.js'
 import { EncoderOptions } from '../core/options.js'
-import {
-  WORD_LENGTH_BITS,
-  WINDOW_SHORT,
-  FFT_SIZE_LOW,
-  FFT_SIZE_MID,
-  FFT_SIZE_HIGH,
-  MDCT_SIZE_SHORT,
-  MDCT_SIZE_MID,
-  MDCT_SIZE_LONG,
-  MDCT_BAND_CONFIGS,
-  MDCT_SHORT_BLOCK_SIZE,
-  MDCT_OVERLAP_SIZE,
-} from '../core/constants.js'
-import { performFFT, detectTransient } from '../analysis/transient.js'
-
-/**
- * QMF Analysis Stage - Splits audio into frequency bands
- *
- * Performs two-stage QMF analysis to decompose the input signal into three bands:
- * - Low band (0-5.5kHz): processed at full resolution
- * - Mid band (5.5-11kHz): processed at half resolution
- * - High band (11-22kHz): processed at quarter resolution with delay compensation
- *
- * @param {Object} context - Pipeline context containing bufferPool
- * @param {BufferPool} context.bufferPool - Shared buffer pool for efficient memory management
- * @returns {Function} Stage function that processes PCM samples
- * @throws {Error} If bufferPool is not provided in context
- */
-export function qmfAnalysisStage(context) {
-  const bufferPool =
-    context?.bufferPool ??
-    throwError('qmfAnalysisStage: bufferPool is required')
-  const delays = bufferPool.qmfDelays
-
-  /**
-   * Process PCM samples through QMF analysis
-   * @param {Float32Array} pcmSamples - Input PCM samples
-   * @returns {Object} Analysis result containing frequency bands
-   * @returns {Array<Float32Array>} returns.bands - Three frequency bands [low, mid, high]
-   */
-  return (pcmSamples) => {
-    const stage1 = qmfAnalysis(
-      pcmSamples,
-      delays.lowBand,
-      bufferPool.qmfWorkBuffers
-    )
-    delays.lowBand = stage1.newDelay
-
-    const stage2 = qmfAnalysis(
-      stage1.lowBand,
-      delays.midBand,
-      bufferPool.qmfWorkBuffers
-    )
-    delays.midBand = stage2.newDelay
-
-    const delayedHigh =
-      bufferPool.qmfWorkBuffers.highBandDelay[stage1.highBand.length]
-    delayedHigh.set(delays.highBand)
-    delayedHigh.set(stage1.highBand, delays.highBand.length)
-
-    const highBand = delayedHigh.slice(0, stage1.highBand.length)
-    delays.highBand = delayedHigh.slice(stage1.highBand.length)
-
-    return {
-      bands: [stage2.lowBand, stage2.highBand, highBand],
-    }
-  }
-}
-
-/**
- * Block Selection Stage - Detects transients to choose transform block sizes
- *
- * Analyzes frequency bands using FFT and transient detection to determine
- * appropriate MDCT block sizes. Short blocks are used for transient signals
- * to prevent pre-echo artifacts, while long blocks provide better frequency
- * resolution for steady-state signals.
- *
- * @param {Object} context - Pipeline context containing bufferPool
- * @param {BufferPool} context.bufferPool - Shared buffer pool for efficient memory management
- * @returns {Function} Stage function that processes QMF analysis results
- * @throws {Error} If bufferPool is not provided in context
- */
-export function blockSelectorStage(context) {
-  const bufferPool =
-    context?.bufferPool ??
-    throwError('blockSelectorStage: bufferPool is required')
-  const options =
-    context?.options ?? throwError('blockSelectorStage: options is required')
-
-  /**
-   * Analyze frequency bands and determine block modes
-   * @param {Object} input - QMF analysis results
-   * @param {Array<Float32Array>} input.bands - Three frequency bands [low, mid, high]
-   * @returns {Object} Block selection results
-   * @returns {Array<Float32Array>} returns.bands - Original frequency bands
-   * @returns {Array<number>} returns.blockModes - Block modes for each band
-   */
-  return (input) => {
-    const { bands } = input
-
-    // 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,
-      blockModes,
-    }
-  }
-}
-
-/**
- * MDCT Transform Stage - Applies Modified Discrete Cosine Transform
- *
- * Transforms time-domain samples to frequency-domain coefficients using MDCT.
- * The transform size depends on the block mode determined by transient detection:
- * - Long blocks: 512/256 samples for better frequency resolution
- * - Short blocks: 64 samples for better time resolution
- *
- * Applies windowing and overlap-add processing to prevent blocking artifacts.
- * Mid and high bands are spectrally reversed to match ATRAC1 format.
- *
- * @param {Object} context - Pipeline context containing bufferPool
- * @param {BufferPool} context.bufferPool - Shared buffer pool for efficient memory management
- * @returns {Function} Stage function that processes block selection results
- * @throws {Error} If bufferPool is not provided in context
- */
-export function mdctStage(context) {
-  const bufferPool =
-    context?.bufferPool ?? throwError('mdctStage: bufferPool is required')
-  const overlapBuffers = bufferPool.mdctOverlap
-
-  // Transform function mapping for each band
-  const TRANSFORM_FUNCS = [mdct256, mdct256, mdct512]
-
-  /**
-   * Transform a single frequency band using MDCT.
-   * @param {Float32Array} samples
-   * @param {number} bandIndex
-   * @param {number} blockMode
-   * @param {Float32Array} overlapBuffer
-   * @param {Object} bufferPool
-   * @returns {Float32Array}
-   */
-  function transformBand(
-    samples,
-    bandIndex,
-    blockMode,
-    overlapBuffer,
-    bufferPool
-  ) {
-    const config = MDCT_BAND_CONFIGS[bandIndex]
-    const transformFunc = TRANSFORM_FUNCS[bandIndex]
-    const isLongBlock = blockMode === 0
-
-    if (isLongBlock) {
-      return transformLongBlock(
-        samples,
-        bandIndex,
-        config,
-        transformFunc,
-        overlapBuffer,
-        bufferPool
-      )
-    } else {
-      return transformShortBlocks(
-        samples,
-        bandIndex,
-        config,
-        overlapBuffer,
-        bufferPool
-      )
-    }
-  }
-
-  /**
-   * Transform using long block (better frequency resolution).
-   * @param {Float32Array} samples
-   * @param {number} bandIndex
-   * @param {Object} config
-   * @param {Object} transformFunc
-   * @param {Float32Array} overlapBuffer
-   * @param {Object} bufferPool
-   * @returns {Float32Array}
-   */
-  function transformLongBlock(
-    samples,
-    bandIndex,
-    config,
-    transformFunc,
-    overlapBuffer,
-    bufferPool
-  ) {
-    const mdctSize = bandIndex === 2 ? MDCT_SIZE_LONG : MDCT_SIZE_MID
-    const mdctInput = bufferPool.transformBuffers[mdctSize]
-    mdctInput.fill(0)
-
-    // Apply overlap from previous frame
-    mdctInput.set(overlapBuffer, config.windowStart)
-
-    // Window and save tail for next frame
-    applyTailWindowing(samples, overlapBuffer, config.size)
-
-    // Add current frame samples
-    mdctInput.set(samples, config.windowStart + MDCT_OVERLAP_SIZE)
-
-    // Transform
-    let spectrum = transformFunc.transform(mdctInput, bufferPool.mdctBuffers)
-
-    // Apply spectral reversal for mid/high bands
-    if (bandIndex > 0) {
-      spectrum = reverseSpectrum(spectrum, bufferPool.reversalBuffers)
-    }
-
-    return spectrum
-  }
-
-  /**
-   * Transform using short blocks (better time resolution for transients).
-   * @param {Float32Array} samples
-   * @param {number} bandIndex
-   * @param {Object} config
-   * @param {Float32Array} overlapBuffer
-   * @param {Object} bufferPool
-   * @returns {Float32Array}
-   */
-  function transformShortBlocks(
-    samples,
-    bandIndex,
-    config,
-    overlapBuffer,
-    bufferPool
-  ) {
-    const numBlocks = 1 << (config.size === 256 ? 3 : 2) // 8 for band 2, 4 for bands 0-1
-    const output = new Float32Array(config.size)
-
-    for (let block = 0; block < numBlocks; block++) {
-      const blockStart = block * MDCT_SHORT_BLOCK_SIZE
-      const blockSamples = samples.subarray(
-        blockStart,
-        blockStart + MDCT_SHORT_BLOCK_SIZE
-      )
-
-      // Prepare MDCT input
-      const mdctInput = bufferPool.transformBuffers[MDCT_SIZE_SHORT]
-      mdctInput.fill(0)
-      mdctInput.set(overlapBuffer, 0)
-
-      // Window and save tail
-      applyTailWindowing(blockSamples, overlapBuffer, MDCT_SHORT_BLOCK_SIZE)
-      mdctInput.set(blockSamples, MDCT_OVERLAP_SIZE)
-
-      // Transform
-      let spectrum = mdct64.transform(mdctInput, bufferPool.mdctBuffers)
-
-      // Apply spectral reversal for mid/high bands
-      if (bandIndex > 0) {
-        spectrum = reverseSpectrum(spectrum, bufferPool.reversalBuffers)
-      }
-
-      output.set(spectrum, blockStart)
-    }
-
-    return output
-  }
-
-  function applyTailWindowing(samples, overlapBuffer, blockSize) {
-    const tailStart = blockSize - MDCT_OVERLAP_SIZE
-    for (let i = 0; i < MDCT_OVERLAP_SIZE; i++) {
-      const tailValue = samples[tailStart + i]
-      overlapBuffer[i] = WINDOW_SHORT[i] * tailValue
-      samples[tailStart + i] = tailValue * WINDOW_SHORT[31 - i]
-    }
-  }
-
-  /**
-   * Transform frequency bands using MDCT
-   * @param {Object} input - Block selection results
-   * @param {Array<Float32Array>} input.bands - Three frequency bands
-   * @param {Array<number>} input.blockModes - Block modes for each band
-   * @param {any} input.originalFrame - Original frame data (passed through)
-   * @returns {Object} MDCT transform results
-   * @returns {Array<Float32Array>} returns.bands - Original frequency bands
-   * @returns {Float32Array} returns.coefficients - MDCT coefficients (512 samples)
-   * @returns {Array<number>} returns.blockModes - Block modes
-   * @returns {any} returns.originalFrame - Original frame data
-   */
-  return (input) => {
-    const { bands, blockModes, originalFrame } = input
-    const coefficients = new Float32Array(512)
-
-    bands.forEach((bandSamples, bandIndex) => {
-      const transformed = transformBand(
-        bandSamples,
-        bandIndex,
-        blockModes[bandIndex],
-        overlapBuffers[bandIndex],
-        bufferPool
-      )
-
-      const offset = calculateBandOffset(bandIndex)
-      coefficients.set(transformed, offset)
-    })
-
-    return { bands, coefficients, blockModes, originalFrame }
-  }
-}
+import { quantize } from '../quantization/stage.js'
+import { BufferPool } from '../state.js'
+import { pipe } from '../utils.js'
 
 /**
- * Quantization Stage - Performs RDO bit allocation and quantization
- *
- * The final encoding stage that:
- * 1. Groups coefficients into Block Floating Units (BFUs)
- * 2. Allocates bits using Rate-Distortion Optimization (RDO)
- * 3. Quantizes coefficients using scale factors and word lengths
- *
- * Uses RDO to optimize the allocation of bits for maximum quality
- * within the available bit budget.
- *
- * @returns {Function} Stage function that processes MDCT results
- * @throws {Error} If bufferPool is not provided in context
- */
-export function quantizationStage(context) {
-  const options =
-    context?.options ?? throwError('quantizationStage: options is required')
-
-  /**
-   * Perform RDO bit allocation and quantization
-   * @param {Object} input - MDCT transform results
-   * @param {Float32Array} input.coefficients - MDCT coefficients
-   * @param {Array<number>} input.blockModes - Block modes
-   * @returns {Object} Quantization results ready for bitstream encoding
-   * @returns {number} returns.nBfu - Number of active BFUs
-   * @returns {Int32Array} returns.scaleFactorIndices - Scale factor indices for each BFU
-   * @returns {Int32Array} returns.wordLengthIndices - Word length indices for each BFU
-   * @returns {Array<Int32Array>} returns.quantizedCoefficients - Quantized coefficient data
-   * @returns {Array<number>} returns.blockModes - Block modes for each band
-   */
-  return (input) => {
-    const { coefficients, blockModes } = input
-
-    const { bfuData, bfuSizes, bfuCount } = groupIntoBFUs(
-      coefficients,
-      blockModes
-    )
-
-    const {
-      bfuCount: selectedBfuCount,
-      allocation,
-      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 = slicedWordLengthIndices[bfu]
-      const bitsPerSample = WORD_LENGTH_BITS[wordLength]
-      const quantized = quantize(data, scaleFactorIndices[bfu], bitsPerSample)
-      quantizedCoefficients.push(quantized)
-    }
-
-    return {
-      nBfu: selectedBfuCount,
-      scaleFactorIndices: slicedScaleFactorIndices,
-      wordLengthIndices: slicedWordLengthIndices,
-      quantizedCoefficients,
-      blockModes,
-    }
-  }
-}
-
-/**
- * Create ATRAC1 encoding pipeline
- *
- * Constructs a complete encoding pipeline that transforms PCM audio samples
- * into ATRAC1 compressed format. The pipeline processes audio through QMF
- * analysis, transient detection, MDCT transform, and psychoacoustic quantization.
- *
- * The returned function can be called repeatedly to encode audio frames,
- * maintaining state through the shared buffer pool for efficient processing.
- *
- * @param {EncoderOptions} [options=new EncoderOptions()] - Encoding configuration
- * @param {BufferPool} [bufferPool=new BufferPool()] - Shared buffer pool for state
- * @returns {Function} Encoding pipeline function that processes PCM samples
+ * Create an ATRAC1 encoder.
  *
- * @example
- * const encoder = encode(new EncoderOptions(), new BufferPool())
- * const result = encoder(pcmSamples) // Returns quantized ATRAC1 frame data
+ * @param {EncoderOptions} [options=new EncoderOptions()]
+ * @param {BufferPool} [bufferPool=new BufferPool()]
+ * @returns {Function}
  */
 export function encode(
   options = new EncoderOptions(),
   bufferPool = new BufferPool()
 ) {
   const context = { options, bufferPool }
-  return pipe(
-    context,
-    qmfAnalysisStage,
-    blockSelectorStage,
-    mdctStage,
-    quantizationStage
-  )
+  return pipe(context, analyze, allocate, quantize)
 }

package/codec/quantization/spectrum.js

@@ -0,0 +1,67 @@
+/**
+ * Carta1 Audio Codec - Spectrum Quantization
+ *
+ * This module handles the quantization and dequantization of MDCT frequency coefficients
+ * for the Carta1 audio codec. It provides functions to convert floating-point frequency
+ * domain data into integer representations suitable for bitstream encoding.
+ *
+ * The quantization process uses configurable scale factors to maintain audio quality
+ * while achieving the target compression ratio. The module supports both uniform
+ * and non-uniform quantization schemes based on perceptual importance.
+ */
+
+import { QUANTIZATION_SIGN_BIT_SHIFT } from '../core/constants.js'
+import { SCALE_FACTORS } from '../core/tables.js'
+
+/**
+ * Quantize coefficients.
+ * @param {Float32Array} coefficients
+ * @param {number} scaleFactorIndex
+ * @param {number} bitsPerSample
+ * @returns {Int32Array} out
+ */
+export function quantize(coefficients, scaleFactorIndex, bitsPerSample) {
+  const length = coefficients.length
+  const out = new Int32Array(length)
+  if (bitsPerSample === 0 || scaleFactorIndex === 0) {
+    out.fill(0, 0, length)
+    return out
+  }
+
+  const scaleFactor = SCALE_FACTORS[scaleFactorIndex]
+  const quantRange = (1 << (bitsPerSample - QUANTIZATION_SIGN_BIT_SHIFT)) - 1
+  const normFactor = quantRange / scaleFactor
+
+  const hi = quantRange
+  const lo = -quantRange
+
+  for (let i = 0; i < length; i++) {
+    const x = coefficients[i] * normFactor
+    const y = (x + (x >= 0 ? 0.5 : -0.5)) | 0
+    out[i] = y > hi ? hi : y < lo ? lo : y
+  }
+
+  return out
+}
+
+/**
+ * Dequantize coefficients.
+ * @param {Int32Array} quantized
+ * @param {number} scaleFactorIndex
+ * @param {number} bitsPerSample
+ * @returns {Float32Array}
+ */
+export function dequantize(quantized, scaleFactorIndex, bitsPerSample) {
+  if (bitsPerSample === 0 || scaleFactorIndex === 0) {
+    return new Float32Array(quantized.length)
+  }
+
+  const scaleFactor = SCALE_FACTORS[scaleFactorIndex]
+  const quantRange = (1 << (bitsPerSample - QUANTIZATION_SIGN_BIT_SHIFT)) - 1
+
+  const deq = new Float32Array(quantized.length)
+  for (let i = 0; i < quantized.length; i++) {
+    deq[i] = (quantized[i] * scaleFactor) / quantRange
+  }
+  return deq
+}

package/codec/quantization/stage.js

@@ -0,0 +1,45 @@
+/**
+ * Carta1 quantization stage.
+ */
+
+import { WORD_LENGTH_BITS } from '../core/tables.js'
+import { quantize as quantizeCoefficient } from './spectrum.js'
+
+/**
+ * Materialize retained allocation as quantized ATRAC1 symbols.
+ *
+ * @returns {QuantizeFrame}
+ */
+export function quantize() {
+  /**
+   * @param {object} input
+   * @returns {object}
+   */
+  return (input) => {
+    const {
+      bfuData,
+      bfuSizes,
+      nBfu,
+      scaleFactorIndices,
+      wordLengthIndices,
+      blockModes,
+    } = input
+    const quantizedCoefficients = []
+
+    for (let bfu = 0; bfu < nBfu; bfu++) {
+      const data = bfuData[bfu].subarray(0, bfuSizes[bfu])
+      const bitsPerSample = WORD_LENGTH_BITS[wordLengthIndices[bfu]]
+      quantizedCoefficients.push(
+        quantizeCoefficient(data, scaleFactorIndices[bfu], bitsPerSample)
+      )
+    }
+
+    return {
+      nBfu,
+      scaleFactorIndices,
+      wordLengthIndices,
+      quantizedCoefficients,
+      blockModes,
+    }
+  }
+}

package/codec/{transforms/qmf.js → signal/bands.js}

@@ -6,7 +6,8 @@
  * bands for independent processing and coding.
  */
 
-import { QMF_DELAY, QMF_EVEN, QMF_ODD } from '../core/constants.js'
+import { QMF_DELAY } from '../core/constants.js'
+import { QMF_EVEN, QMF_ODD } from '../core/tables.js'
 import { throwError } from '../utils.js'
 
 /**
@@ -16,13 +17,15 @@ import { throwError } from '../utils.js'
  * @param {Object} qmfWorkBuffers - Optional work buffers for processing
  * @returns {Object} Object containing lowBand, highBand, and newDelay
  */
-export function qmfAnalysis(input, delayLine, qmfWorkBuffers = null) {
+export function analyzeQmfPair(input, delayLine, qmfWorkBuffers = null) {
   const inputLength = input.length
   const outputLength = inputLength >> 1
 
   const workBuffer =
     qmfWorkBuffers?.delay?.[inputLength] ??
-    throwError(`qmfAnalysis: qmfWorkBuffers.delay[${inputLength}] is required`)
+    throwError(
+      `analyzeQmfPair: qmfWorkBuffers.delay[${inputLength}] is required`
+    )
   workBuffer.set(delayLine)
   workBuffer.set(input, delayLine.length)
 
@@ -57,7 +60,7 @@ export function qmfAnalysis(input, delayLine, qmfWorkBuffers = null) {
  * @param {Object} qmfWorkBuffers - Optional work buffers for processing
  * @returns {Object} Object containing output and newDelay
  */
-export function qmfSynthesis(
+export function synthesizeQmfPair(
   lowBand,
   highBand,
   delayLine,
@@ -69,7 +72,7 @@ export function qmfSynthesis(
   const workBuffer =
     qmfWorkBuffers?.delay?.[outputLength] ??
     throwError(
-      `qmfSynthesis: qmfWorkBuffers.delay[${outputLength}] is required`
+      `synthesizeQmfPair: qmfWorkBuffers.delay[${outputLength}] is required`
     )
   workBuffer.set(delayLine)
 

package/codec/{transforms → signal}/fft.js

@@ -1,5 +1,5 @@
 /**
- * Carta1 Audio Codec - Fast Fourier Transform
+ * Carta1 Fast Fourier Transform operator.
  *
  * This module implements a radix-2 Cooley-Tukey FFT algorithm for frequency domain
  * analysis used in psychoacoustic modeling and transient detection.

package/codec/{transforms/mdct.js → signal/spectrum.js}

@@ -1,5 +1,5 @@
 /**
- * Carta1 Audio Codec - Modified Discrete Cosine Transform
+ * Carta1 spectrum signal operators.
  *
  * This module implements forward and inverse MDCT transforms for the ATRAC1 codec.
  * The MDCT provides time-frequency analysis with perfect reconstruction and
@@ -243,3 +243,18 @@ export function overlapAdd(prev, curr, window) {
 
   return output
 }
+
+/**
+ * Reverse spectral order for ATRAC1 mid and high bands.
+ *
+ * @param {Float32Array} spectrum
+ * @param {Object} reversalBuffers
+ * @returns {Float32Array}
+ */
+export function reverseSpectrum(spectrum, reversalBuffers) {
+  const reversed = reversalBuffers[spectrum.length]
+  for (let i = 0; i < spectrum.length; i++) {
+    reversed[i] = spectrum[spectrum.length - 1 - i]
+  }
+  return reversed
+}