carta1 1.0.0

package/codec/pipeline/encoder.js

@@ -0,0 +1,369 @@
+/**
+ * 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.
+ */
+
+import { pipe, throwError } from '../utils.js'
+import { qmfAnalysis } from '../transforms/qmf.js'
+import { mdct64, mdct256, mdct512 } from '../transforms/mdct.js'
+import {
+  groupIntoBFUs,
+  findScaleFactor,
+  quantize,
+} from '../coding/quantization.js'
+import { allocateBits } from '../coding/bitallocation.js'
+import { BufferPool } from '../core/buffers.js'
+import { EncoderOptions } from '../core/options.js'
+import {
+  WORD_LENGTH_BITS,
+  WINDOW_SHORT,
+  FFT_SIZE_LOW,
+  FFT_SIZE_MID,
+  FFT_SIZE_HIGH,
+  PSYMODEL_FFT_SIZE,
+  MDCT_SIZE_SHORT,
+  MDCT_SIZE_MID,
+  MDCT_SIZE_LONG,
+} from '../core/constants.js'
+import { performFFT, detectTransient } from '../analysis/transient.js'
+import { psychoAnalysis } from '../analysis/psychoacoustics.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
+ */
+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
+ */
+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 mode indices for each band
+   */
+  return (input) => {
+    const { bands } = input
+    const [lowBand, midBand, highBand] = bands
+
+    const lowCoeffs = performFFT(lowBand, FFT_SIZE_LOW)
+    const midCoeffs = performFFT(midBand, FFT_SIZE_MID)
+    const highCoeffs = performFFT(highBand, FFT_SIZE_HIGH)
+
+    const lowTransient = detectTransient(
+      lowCoeffs,
+      bufferPool.transientDetection.prevLowCoeffs,
+      options.transientThresholdLow
+    )
+    const midTransient = detectTransient(
+      midCoeffs,
+      bufferPool.transientDetection.prevMidCoeffs,
+      options.transientThresholdMid
+    )
+    const highTransient = detectTransient(
+      highCoeffs,
+      bufferPool.transientDetection.prevHighCoeffs,
+      options.transientThresholdHigh
+    )
+
+    bufferPool.transientDetection.prevLowCoeffs = lowCoeffs
+    bufferPool.transientDetection.prevMidCoeffs = midCoeffs
+    bufferPool.transientDetection.prevHighCoeffs = highCoeffs
+
+    return {
+      bands,
+      blockModes: [
+        lowTransient ? 2 : 0,
+        midTransient ? 2 : 0,
+        highTransient ? 3 : 0,
+      ],
+    }
+  }
+}
+
+/**
+ * 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
+ */
+function mdctStage(context) {
+  const bufferPool =
+    context?.bufferPool ?? throwError('mdctStage: bufferPool is required')
+  const overlapBuffers = bufferPool.mdctOverlap
+
+  /**
+   * 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 mode indices 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 mode indices
+   * @returns {any} returns.originalFrame - Original frame data
+   */
+  return (input) => {
+    const { bands, blockModes, originalFrame } = input
+
+    const coefficients = new Float32Array(512)
+
+    for (let band = 0; band < 3; band++) {
+      const samples = bands[band]
+      const bandSize = band === 2 ? 256 : 128
+      const numBlocks = 1 << blockModes[band]
+      const blockSize = numBlocks === 1 ? bandSize : 32
+
+      const mdctFunc =
+        numBlocks === 1 ? (band === 2 ? mdct512 : mdct256) : mdct64
+      const mdctSize =
+        numBlocks === 1
+          ? band === 2
+            ? MDCT_SIZE_LONG
+            : MDCT_SIZE_MID
+          : MDCT_SIZE_SHORT
+      const windowStart = numBlocks === 1 ? (band === 2 ? 112 : 48) : 0
+
+      const offset = band === 0 ? 0 : band === 1 ? 128 : 256
+
+      for (let block = 0; block < numBlocks; block++) {
+        const blockStart = block * blockSize
+        const mdctInput = bufferPool.transformBuffers[mdctSize]
+        mdctInput.fill(0)
+
+        mdctInput.set(overlapBuffers[band], windowStart)
+
+        for (let i = 0; i < 32; i++) {
+          const tailValue = samples[blockStart + blockSize - 32 + i]
+          overlapBuffers[band][i] = WINDOW_SHORT[i] * tailValue
+          samples[blockStart + blockSize - 32 + i] =
+            tailValue * WINDOW_SHORT[31 - i]
+        }
+
+        mdctInput.set(
+          samples.subarray(blockStart, blockStart + blockSize),
+          windowStart + 32
+        )
+
+        let spectrum = mdctFunc.transform(mdctInput, bufferPool.mdctBuffers)
+
+        if (band > 0) {
+          const reversed = bufferPool.reversalBuffers[spectrum.length]
+          reversed.fill(0)
+          for (let i = 0; i < spectrum.length; i++) {
+            reversed[i] = spectrum[spectrum.length - 1 - i]
+          }
+          spectrum = reversed
+        }
+
+        coefficients.set(spectrum, offset + blockStart)
+      }
+    }
+
+    return { bands, coefficients, blockModes, originalFrame }
+  }
+}
+
+/**
+ * Quantization Stage - Performs psychoacoustic analysis and quantization
+ *
+ * The final encoding stage that:
+ * 1. Groups coefficients into Block Floating Units (BFUs)
+ * 2. Performs psychoacoustic analysis to determine masking thresholds
+ * 3. Allocates bits based on perceptual importance
+ * 4. Quantizes coefficients using scale factors and word lengths
+ *
+ * Uses a perceptual model to ensure quantization noise remains below
+ * the masking threshold, maximizing quality within the bit budget.
+ *
+ * @param {Object} context - Pipeline context containing bufferPool and options
+ * @param {BufferPool} context.bufferPool - Shared buffer pool for efficient memory management
+ * @param {EncoderOptions} context.options - Encoding configuration options
+ * @returns {Function} Stage function that processes MDCT results
+ * @throws {Error} If bufferPool or options are not provided in context
+ */
+function quantizationStage(context) {
+  const bufferPool =
+    context?.bufferPool ??
+    throwError('quantizationStage: bufferPool is required')
+  const options =
+    context?.options ?? throwError('quantizationStage: options is required')
+
+  /**
+   * Perform psychoacoustic analysis and quantization
+   * @param {Object} input - MDCT transform results
+   * @param {Float32Array} input.coefficients - MDCT coefficients
+   * @param {Array<number>} input.blockModes - Block mode indices
+   * @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.blockSizeMode - Block size mode for each band
+   */
+  return (input) => {
+    const { coefficients, blockModes } = input
+
+    const { bfuData, bfuSizes, bfuCount } = groupIntoBFUs(
+      coefficients,
+      blockModes,
+      bufferPool.bfuData
+    )
+
+    const psychoResults = psychoAnalysis(
+      coefficients,
+      PSYMODEL_FFT_SIZE,
+      bufferPool.psychoAnalysis,
+      options.normalizationDb
+    )
+    const { bfuCount: selectedBfuCount, allocation } = allocateBits(
+      psychoResults,
+      bfuData,
+      bfuSizes,
+      bfuCount
+    )
+
+    const scaleFactorIndices = new Int32Array(selectedBfuCount)
+    const quantizedCoefficients = []
+
+    for (let bfu = 0; bfu < selectedBfuCount; bfu++) {
+      const data = bfuData[bfu].subarray(0, bfuSizes[bfu])
+      const wordLength = allocation[bfu]
+      const bitsPerSample = WORD_LENGTH_BITS[wordLength]
+
+      scaleFactorIndices[bfu] = findScaleFactor(data)
+      const quantized = quantize(data, scaleFactorIndices[bfu], bitsPerSample)
+      quantizedCoefficients.push(quantized)
+    }
+
+    return {
+      nBfu: selectedBfuCount,
+      scaleFactorIndices,
+      wordLengthIndices: allocation.slice(0, selectedBfuCount),
+      quantizedCoefficients,
+      blockSizeMode: 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
+ *
+ * @example
+ * const encoder = encode(new EncoderOptions(), new BufferPool())
+ * const result = encoder(pcmSamples) // Returns quantized ATRAC1 frame data
+ */
+export function encode(
+  options = new EncoderOptions(),
+  bufferPool = new BufferPool()
+) {
+  const context = { options, bufferPool }
+  return pipe(
+    context,
+    qmfAnalysisStage,
+    blockSelectorStage,
+    mdctStage,
+    quantizationStage
+  )
+}

package/codec/transforms/fft.js

@@ -0,0 +1,69 @@
+/**
+ * Carta1 Audio Codec - Fast Fourier Transform
+ *
+ * This module implements a radix-2 Cooley-Tukey FFT algorithm for frequency domain
+ * analysis used in psychoacoustic modeling and transient detection.
+ */
+
+export class FFT {
+  /**
+   * Perform in-place FFT on complex data
+   * @param {Float32Array} real - Real part of input/output data
+   * @param {Float32Array} imag - Imaginary part of input/output data
+   */
+  static fft(real, imag) {
+    const size = real.length
+    if (size === 1) return
+
+    const bits = Math.log2(size)
+
+    // Bit reversal
+    for (let i = 0; i < size; i++) {
+      let reversed = 0
+      let temp = i
+      for (let b = 0; b < bits; b++) {
+        reversed = (reversed << 1) | (temp & 1)
+        temp >>= 1
+      }
+      if (reversed > i) {
+        ;[real[i], real[reversed]] = [real[reversed], real[i]]
+        ;[imag[i], imag[reversed]] = [imag[reversed], imag[i]]
+      }
+    }
+
+    // Cooley-Tukey decimation-in-time
+    for (let stride = 2; stride <= size; stride <<= 1) {
+      const halfStride = stride >> 1
+      const angle = (-2 * Math.PI) / stride
+      const wReal = Math.cos(angle)
+      const wImag = Math.sin(angle)
+
+      for (let start = 0; start < size; start += stride) {
+        let twiddleReal = 1
+        let twiddleImag = 0
+
+        for (let k = 0; k < halfStride; k++) {
+          const evenIndex = start + k
+          const oddIndex = evenIndex + halfStride
+
+          const evenReal = real[evenIndex]
+          const evenImag = imag[evenIndex]
+          const oddReal = real[oddIndex]
+          const oddImag = imag[oddIndex]
+
+          const tReal = oddReal * twiddleReal - oddImag * twiddleImag
+          const tImag = oddReal * twiddleImag + oddImag * twiddleReal
+
+          real[evenIndex] = evenReal + tReal
+          imag[evenIndex] = evenImag + tImag
+          real[oddIndex] = evenReal - tReal
+          imag[oddIndex] = evenImag - tImag
+
+          const nextReal = twiddleReal * wReal - twiddleImag * wImag
+          twiddleImag = twiddleReal * wImag + twiddleImag * wReal
+          twiddleReal = nextReal
+        }
+      }
+    }
+  }
+}

package/codec/transforms/mdct.js

@@ -0,0 +1,225 @@
+/**
+ * Carta1 Audio Codec - Modified Discrete Cosine Transform
+ *
+ * This module implements forward and inverse MDCT transforms for the ATRAC1 codec.
+ * The MDCT provides time-frequency analysis with perfect reconstruction and
+ * 50% overlap between adjacent blocks to avoid blocking artifacts.
+ */
+
+import { FFT } from './fft.js'
+import {
+  MDCT_SIZE_SHORT,
+  MDCT_SIZE_MID,
+  MDCT_SIZE_LONG,
+} from '../core/constants.js'
+import { throwError } from '../utils.js'
+
+/**
+ * Base class for MDCT and IMDCT transforms
+ */
+class MDCTBase {
+  constructor(size, scale) {
+    this.size = size
+    this.halfSize = size >> 1
+    this.quarterSize = size >> 2
+    this.fftSize = this.halfSize >> 1
+
+    const alpha = (2.0 * Math.PI) / (8.0 * size)
+    const omega = (2.0 * Math.PI) / size
+    const scaleRoot = Math.sqrt(scale / size)
+
+    this.sinCosTable = new Float32Array(this.halfSize)
+    for (let i = 0; i < this.quarterSize; i++) {
+      const angle = omega * i + alpha
+      this.sinCosTable[i * 2] = scaleRoot * Math.cos(angle)
+      this.sinCosTable[i * 2 + 1] = scaleRoot * Math.sin(angle)
+    }
+  }
+}
+
+/**
+ * Forward MDCT transform
+ */
+export class MDCT extends MDCTBase {
+  constructor(size, scale) {
+    super(size, scale)
+  }
+
+  /**
+   * Perform forward MDCT transform
+   * @param {Float32Array} input - Time-domain input samples
+   * @param {Object} mdctBuffers - Optional work buffers for FFT
+   * @returns {Float32Array} Frequency-domain MDCT coefficients
+   */
+  transform(input, mdctBuffers = null) {
+    const buffers = mdctBuffers?.[this.fftSize]
+    const real = buffers?.real ?? throwError('mdct: real is required')
+    const imag = buffers?.imag ?? throwError('mdct: imag is required')
+
+    const n4 = this.quarterSize
+    const n34 = 3 * n4
+
+    real.fill(0)
+    imag.fill(0)
+
+    // Pre-FFT butterfly
+    for (let i = 0; i < n4; i += 2) {
+      const i1 = n34 - 1 - i
+      const i2 = n34 + i
+      const i3 = n4 + i
+      const i4 = n4 - 1 - i
+
+      const r = input[i1] + input[i2]
+      const im = input[i3] - input[i4]
+      const c = this.sinCosTable[i]
+      const s = this.sinCosTable[i + 1]
+
+      real[i >> 1] = r * c + im * s
+      imag[i >> 1] = im * c - r * s
+    }
+
+    for (let i = n4; i < this.halfSize; i += 2) {
+      const idx = i >> 1
+      const i1 = n34 - 1 - i
+      const i2 = i - n4
+      const i3 = n4 + i
+      const i4 = 5 * n4 - 1 - i
+
+      const r = input[i1] - input[i2]
+      const im = input[i3] + input[i4]
+      const c = this.sinCosTable[i]
+      const s = this.sinCosTable[i + 1]
+
+      real[idx] = r * c + im * s
+      imag[idx] = im * c - r * s
+    }
+
+    FFT.fft(real, imag)
+
+    // Post-FFT processing
+    const output = new Float32Array(this.halfSize)
+    for (let i = 0; i < this.fftSize; i++) {
+      const c = this.sinCosTable[i * 2]
+      const s = this.sinCosTable[i * 2 + 1]
+      const re = real[i]
+      const im = imag[i]
+
+      output[i * 2] = -re * c - im * s
+      output[this.halfSize - 1 - i * 2] = -re * s + im * c
+    }
+
+    return output
+  }
+}
+
+/**
+ * Inverse MDCT transform
+ */
+export class IMDCT extends MDCTBase {
+  constructor(size, scale = null) {
+    super(size, scale || size)
+  }
+
+  /**
+   * Perform inverse MDCT transform
+   * @param {Float32Array} input - Frequency-domain MDCT coefficients
+   * @param {Object} mdctBuffers - Optional work buffers for FFT
+   * @returns {Float32Array} Time-domain output samples
+   */
+  transform(input, mdctBuffers = null) {
+    const buffers = mdctBuffers?.[this.fftSize]
+    const real = buffers?.real ?? throwError('imdct: real is required')
+    const imag = buffers?.imag ?? throwError('imdct: imag is required')
+
+    const n4 = this.quarterSize
+    const n34 = 3 * n4
+
+    real.fill(0)
+    imag.fill(0)
+
+    // Pre-FFT processing
+    for (let i = 0; i < this.fftSize; i++) {
+      const i2 = i * 2
+      const r = input[i2]
+      const im = input[this.halfSize - 1 - i2]
+      const c = this.sinCosTable[i2]
+      const s = this.sinCosTable[i2 + 1]
+
+      real[i] = -2.0 * (im * s + r * c)
+      imag[i] = -2.0 * (im * c - r * s)
+    }
+
+    FFT.fft(real, imag)
+
+    // Post-FFT butterfly
+    const output = new Float32Array(this.size)
+
+    for (let i = 0; i < this.fftSize / 2; i++) {
+      const i2 = i * 2
+      const c = this.sinCosTable[i2]
+      const s = this.sinCosTable[i2 + 1]
+      const re = real[i]
+      const im = imag[i]
+
+      const r1 = re * c + im * s
+      const i1 = re * s - im * c
+
+      output[n34 - 1 - i2] = r1
+      output[n34 + i2] = r1
+      output[n4 + i2] = i1
+      output[n4 - 1 - i2] = -i1
+    }
+
+    for (let i = this.fftSize / 2; i < this.fftSize; i++) {
+      const idx = (i - this.fftSize / 2) * 2 + n4
+      const i2 = i * 2
+      const c = this.sinCosTable[i2]
+      const s = this.sinCosTable[i2 + 1]
+      const re = real[i]
+      const im = imag[i]
+
+      const r1 = re * c + im * s
+      const i1 = re * s - im * c
+
+      output[n34 - 1 - idx] = r1
+      output[idx - n4] = -r1
+      output[n4 + idx] = i1
+      output[5 * n4 - 1 - idx] = i1
+    }
+
+    return output
+  }
+}
+
+// Pre-instantiated transforms
+export const mdct64 = new MDCT(MDCT_SIZE_SHORT, 0.5)
+export const mdct256 = new MDCT(MDCT_SIZE_MID, 0.5)
+export const mdct512 = new MDCT(MDCT_SIZE_LONG, 1.0)
+
+export const imdct64 = new IMDCT(MDCT_SIZE_SHORT, MDCT_SIZE_SHORT * 4)
+export const imdct256 = new IMDCT(MDCT_SIZE_MID, MDCT_SIZE_MID * 4)
+export const imdct512 = new IMDCT(MDCT_SIZE_LONG, MDCT_SIZE_LONG * 2)
+
+/**
+ * Perform overlap-add operation for MDCT reconstruction
+ * @param {Float32Array} prev - Previous block samples
+ * @param {Float32Array} curr - Current block samples
+ * @param {Float32Array} window - Window function coefficients
+ * @returns {Float32Array} Overlap-added output samples
+ */
+export function overlapAdd(prev, curr, window) {
+  const size = prev.length
+  const output = new Float32Array(size * 2)
+
+  for (let i = 0; i < size; i++) {
+    const w1 = window[i]
+    const w2 = window[2 * size - 1 - i]
+    const p = prev[i]
+    const c = curr[size - 1 - i]
+
+    output[i] = p * w2 - c * w1
+    output[2 * size - 1 - i] = p * w1 + c * w2
+  }
+
+  return output
+}