carta1 1.1.10 → 1.2.0

package/codec/{core/buffers.js → state.js}

@@ -1,12 +1,45 @@
 /**
- * Carta1 Audio Codec - Buffer Management
+ * Carta1 stream state and reusable scratch.
  */
 
-import { QMF_DELAY, QMF_HIGH_BAND_DELAY } from './constants.js'
+import { QMF_DELAY, QMF_HIGH_BAND_DELAY } from './core/constants.js'
 
-export class BufferPool {
+/**
+ * Values with meaning across chronological frames.
+ */
+class History {
+  constructor() {
+    this.qmfDelays = {
+      lowBand: new Float32Array(QMF_DELAY),
+      midBand: new Float32Array(QMF_DELAY),
+      highBand: new Float32Array(QMF_HIGH_BAND_DELAY),
+    }
+
+    this.transientDetection = [
+      new Float32Array(64),
+      new Float32Array(64),
+      new Float32Array(128),
+    ]
+
+    this.mdctOverlap = [
+      new Float32Array(32),
+      new Float32Array(32),
+      new Float32Array(32),
+    ]
+
+    this.imdctOverlap = [
+      new Float32Array(256),
+      new Float32Array(256),
+      new Float32Array(512),
+    ]
+  }
+}
+
+/**
+ * Reusable storage with no meaning between operations.
+ */
+class Scratch {
   constructor() {
-    // Transform buffers
     this.transformBuffers = {
       64: new Float32Array(64),
       128: new Float32Array(128),
@@ -14,7 +47,6 @@ export class BufferPool {
       512: new Float32Array(512),
     }
 
-    // QMF work buffers
     this.qmfWorkBuffers = {
       delay: {
         128: new Float32Array(QMF_DELAY + 128),
@@ -27,21 +59,6 @@ export class BufferPool {
       },
     }
 
-    // QMF delay lines
-    this.qmfDelays = {
-      lowBand: new Float32Array(QMF_DELAY),
-      midBand: new Float32Array(QMF_DELAY),
-      highBand: new Float32Array(QMF_HIGH_BAND_DELAY),
-    }
-
-    // Transient detector
-    this.transientDetection = [
-      new Float32Array(64),
-      new Float32Array(64),
-      new Float32Array(128),
-    ]
-
-    // MDCT/IMDCT work buffers
     this.mdctBuffers = {
       16: {
         real: new Float32Array(16),
@@ -57,21 +74,6 @@ export class BufferPool {
       },
     }
 
-    // MDCT overlap buffers (encoder)
-    this.mdctOverlap = [
-      new Float32Array(32),
-      new Float32Array(32),
-      new Float32Array(32),
-    ]
-
-    // IMDCT overlap buffers (decoder)
-    this.imdctOverlap = [
-      new Float32Array(256),
-      new Float32Array(256),
-      new Float32Array(512),
-    ]
-
-    // Spectrum reversal buffers
     this.reversalBuffers = {
       32: new Float32Array(32),
       128: new Float32Array(128),
@@ -79,3 +81,12 @@ export class BufferPool {
     }
   }
 }
+
+/**
+ * Own one chronological stream's history and reusable storage.
+ */
+export class BufferPool {
+  constructor() {
+    Object.assign(this, new History(), new Scratch())
+  }
+}

package/codec/{io → syntax}/bitstream.js

@@ -1,24 +1,40 @@
 /**
- * Carta1 Audio Codec - Bitstream Operations
+ * Carta1 bitstream syntax operators.
  *
  * This module provides low-level bitstream packing and unpacking operations
  * for reading and writing ATRAC1 frame data with bit-level precision.
  */
 
+/**
+ * Reject field widths outside the shared bitstream primitive's safe range.
+ *
+ * @param {number} bitCount
+ * @returns {void}
+ */
+function assertBitCount(bitCount) {
+  if (!Number.isInteger(bitCount) || bitCount < 0 || bitCount > 32) {
+    throw new RangeError(
+      `Bit count must be an integer in 0..32, got ${bitCount}`
+    )
+  }
+}
+
 /**
  * Pack bits into a buffer at a specific bit position
  * @param {Uint8Array} buffer - Destination buffer
  * @param {number} bitPosition - Bit position to start writing at
  * @param {number} value - Value to pack
  * @param {number} bitCount - Number of bits to pack
+ * @returns {void}
  */
 export function packBits(buffer, bitPosition, value, bitCount) {
+  assertBitCount(bitCount)
   if (bitCount === 0) return
 
   let byteIndex = Math.floor(bitPosition / 8)
   let bitOffset = bitPosition % 8
 
-  value &= (1 << bitCount) - 1
+  const unsignedValue = Number(value) >>> 0
 
   let bitsWritten = 0
   while (bitsWritten < bitCount && byteIndex < buffer.length) {
@@ -26,9 +42,9 @@ export function packBits(buffer, bitPosition, value, bitCount) {
     const bitsToWrite = Math.min(bitCount - bitsWritten, bitsAvailable)
 
     const shift = bitCount - bitsWritten - bitsToWrite
-    const valueBits = (value >> shift) & ((1 << bitsToWrite) - 1)
+    const valueBits = (unsignedValue >>> shift) & (2 ** bitsToWrite - 1)
 
-    const mask = ((1 << bitsToWrite) - 1) << (bitsAvailable - bitsToWrite)
+    const mask = (2 ** bitsToWrite - 1) << (bitsAvailable - bitsToWrite)
     buffer[byteIndex] =
       (buffer[byteIndex] & ~mask) | (valueBits << (bitsAvailable - bitsToWrite))
 
@@ -46,6 +62,7 @@ export function packBits(buffer, bitPosition, value, bitCount) {
  * @returns {number} Unpacked unsigned value
  */
 export function unpackBits(buffer, bitPosition, bitCount) {
+  assertBitCount(bitCount)
   if (bitCount === 0) return 0
 
   let byteIndex = Math.floor(bitPosition / 8)
@@ -56,10 +73,10 @@ export function unpackBits(buffer, bitPosition, bitCount) {
     const bitsAvailable = 8 - bitOffset
     const bitsToRead = Math.min(bitCount - bitsRead, bitsAvailable)
 
-    const mask = (1 << bitsToRead) - 1
+    const mask = 2 ** bitsToRead - 1
     const bits = (buffer[byteIndex] >> (bitsAvailable - bitsToRead)) & mask
 
-    value = (value << bitsToRead) | bits
+    value = (value * 2 ** bitsToRead + bits) >>> 0
     bitsRead += bitsToRead
     byteIndex++
     bitOffset = 0
@@ -76,7 +93,9 @@ export function unpackBits(buffer, bitPosition, bitCount) {
  * @returns {number} Unpacked signed value (two's complement)
  */
 export function unpackSignedBits(buffer, bitPosition, bitCount) {
+  assertBitCount(bitCount)
+  if (bitCount === 0) return 0
   const value = unpackBits(buffer, bitPosition, bitCount)
-  const signBit = 1 << (bitCount - 1)
-  return value >= signBit ? value - (1 << bitCount) : value
+  const signBit = 2 ** (bitCount - 1)
+  return value >= signBit ? value - 2 ** bitCount : value
 }

package/codec/{io/serialization.js → syntax/frame.js}

@@ -1,7 +1,7 @@
 /**
- * Carta1 Audio Codec - Serialization Module
+ * Carta1 structured-frame syntax.
  *
- * Handles serialization and deserialization of ATRAC1 audio frames and AEA file format.
+ * Handles serialization and deserialization of ATRAC1 audio frames.
  * Provides functions for packing encoded frame data into binary format and unpacking
  * it back into structured data for processing.
  *
@@ -13,29 +13,16 @@
 
 import {
   SOUND_UNIT_SIZE,
-  BFU_AMOUNTS,
-  SPECS_PER_BFU,
-  AEA_HEADER_SIZE,
-  AEA_MAGIC,
-  AEA_TITLE_OFFSET,
-  AEA_TITLE_SIZE,
-  AEA_FRAME_COUNT_OFFSET,
-  AEA_CHANNEL_COUNT_OFFSET,
-  WORD_LENGTH_BITS,
   FRAME_HEADER_BITS,
   FRAME_WORD_LENGTH_BITS,
   FRAME_SCALE_FACTOR_BITS,
 } from '../core/constants.js'
+import { BFU_AMOUNTS, SPECS_PER_BFU, WORD_LENGTH_BITS } from '../core/tables.js'
 import { packBits, unpackBits, unpackSignedBits } from './bitstream.js'
 
 /**
  * Serializes encoded frame data into binary format
- * @param {Object} frameData - The encoded frame data to serialize
- * @param {number} frameData.nBfu - Number of block floating units
- * @param {number[]} frameData.blockModes - Block modes for each band [0-2]
- * @param {Int32Array} frameData.scaleFactorIndices - Scale factor indices for each BFU
- * @param {Int32Array} frameData.wordLengthIndices - Word length indices for each BFU
- * @param {Int32Array[]} frameData.quantizedCoefficients - Quantized spectral coefficients
+ * @param {object} frameData - The encoded frame data to serialize
  * @returns {Uint8Array} Serialized frame data buffer
  */
 export function serializeFrame(frameData) {
@@ -100,12 +87,7 @@ export function serializeFrame(frameData) {
 /**
  * Deserializes binary frame data back into structured format
  * @param {Uint8Array} buffer - Binary frame data buffer
- * @returns {Object} Deserialized frame data
- * @returns {number} returns.nBfu - Number of block floating units
- * @returns {number[]} returns.blockModes - Block modes for each band
- * @returns {Int32Array} returns.scaleFactorIndices - Scale factor indices for each BFU
- * @returns {Int32Array} returns.wordLengthIndices - Word length indices for each BFU
- * @returns {Int32Array[]} returns.quantizedCoefficients - Quantized spectral coefficients
+ * @returns {object} Deserialized frame data
  * @throws {Error} If buffer size is invalid
  */
 export function deserializeFrame(buffer) {
@@ -174,81 +156,3 @@ export function deserializeFrame(buffer) {
     blockModes,
   }
 }
-
-/**
- * AEA file format handler for ATRAC1 audio files
- * Manages creation and parsing of AEA file headers
- */
-export class AeaFile {
-  /**
-   * Creates an AEA file header with the specified metadata
-   * @param {string} [title=''] - Audio file title (max 255 characters)
-   * @param {number} [frameCount=0] - Number of audio frames in the file
-   * @param {number} [channelCount=1] - Number of audio channels (1 or 2)
-   * @returns {Uint8Array} AEA file header buffer
-   */
-  static createHeader(title = '', frameCount = 0, channelCount = 1) {
-    const header = new Uint8Array(AEA_HEADER_SIZE)
-    const view = new DataView(header.buffer)
-
-    // Magic number
-    header.set(AEA_MAGIC, 0)
-
-    // Title (null-terminated string)
-    const titleBytes = new TextEncoder().encode(title)
-    header.set(
-      titleBytes.subarray(0, Math.min(titleBytes.length, AEA_TITLE_SIZE - 1)),
-      AEA_TITLE_OFFSET
-    )
-
-    // Frame count
-    view.setUint32(AEA_FRAME_COUNT_OFFSET, frameCount, true)
-
-    // Channel count
-    header[AEA_CHANNEL_COUNT_OFFSET] = channelCount
-
-    return header
-  }
-
-  /**
-   * Parses an AEA file header to extract metadata
-   * @param {Uint8Array} header - AEA file header buffer
-   * @returns {Object} Parsed header information
-   * @returns {string} returns.title - Audio file title
-   * @returns {number} returns.frameCount - Number of audio frames
-   * @returns {number} returns.channelCount - Number of audio channels
-   * @throws {Error} If header size is invalid or magic number doesn't match
-   */
-  static parseHeader(header) {
-    if (header.length !== AEA_HEADER_SIZE) {
-      throw new Error(`Header must be ${AEA_HEADER_SIZE} bytes`)
-    }
-
-    // Check magic number
-    for (let i = 0; i < AEA_MAGIC.length; i++) {
-      if (header[i] !== AEA_MAGIC[i]) {
-        throw new Error('Invalid AEA file')
-      }
-    }
-
-    const view = new DataView(
-      header.buffer,
-      header.byteOffset,
-      header.byteLength
-    )
-
-    // Extract title
-    const titleEnd = header.indexOf(0, AEA_TITLE_OFFSET)
-    const titleLength =
-      titleEnd === -1 ? AEA_TITLE_SIZE : titleEnd - AEA_TITLE_OFFSET
-    const title = new TextDecoder().decode(
-      header.subarray(AEA_TITLE_OFFSET, AEA_TITLE_OFFSET + titleLength)
-    )
-
-    // Extract metadata
-    const frameCount = view.getUint32(AEA_FRAME_COUNT_OFFSET, true)
-    const channelCount = header[AEA_CHANNEL_COUNT_OFFSET]
-
-    return { title, frameCount, channelCount }
-  }
-}

package/codec/synthesis/bands.js

@@ -0,0 +1,201 @@
+/**
+ * Carta1 spectral synthesis application.
+ */
+
+import {
+  MDCT_SHORT_BLOCK_SIZE,
+  MDCT_SIZE_LONG,
+  MDCT_TAIL_WINDOW_SIZE,
+} from '../core/constants.js'
+import { extractBandCoefficients } from '../core/geometry.js'
+import { MDCT_BAND_CONFIGS, WINDOW_SHORT } from '../core/tables.js'
+import {
+  imdct64,
+  imdct256,
+  imdct512,
+  overlapAdd,
+  reverseSpectrum,
+} from '../signal/spectrum.js'
+import { throwError } from '../utils.js'
+
+/**
+ * Synthesize time-domain bands from the ATRAC1 spectrum.
+ *
+ * @param {object} context
+ * @returns {Function}
+ * @throws {Error} If the buffer pool is missing
+ */
+export function synthesizeSpectrum(context) {
+  const bufferPool =
+    context?.bufferPool ??
+    throwError('synthesizeSpectrum: bufferPool is required')
+  const overlapBuffers = bufferPool.imdctOverlap
+  const transformFunctions = [imdct256, imdct256, imdct512]
+
+  /**
+   * @param {Float32Array} coefficients
+   * @param {number} bandIndex
+   * @param {number} blockMode
+   * @param {Float32Array} overlapBuffer
+   * @param {Object} config
+   * @returns {Float32Array}
+   */
+  function transformBand(
+    coefficients,
+    bandIndex,
+    blockMode,
+    overlapBuffer,
+    config
+  ) {
+    if (blockMode === 0) {
+      return inverseLongBlock(
+        coefficients,
+        bandIndex,
+        overlapBuffer,
+        config,
+        transformFunctions[bandIndex]
+      )
+    }
+
+    return inverseShortBlocks(coefficients, bandIndex, overlapBuffer, config)
+  }
+
+  /**
+   * @param {Float32Array} coefficients
+   * @param {number} bandIndex
+   * @param {Float32Array} overlapBuffer
+   * @param {Object} config
+   * @param {Object} transformFunction
+   * @returns {Float32Array}
+   */
+  function inverseLongBlock(
+    coefficients,
+    bandIndex,
+    overlapBuffer,
+    config,
+    transformFunction
+  ) {
+    let blockSpectrum = coefficients
+    if (bandIndex > 0) {
+      blockSpectrum = reverseSpectrum(coefficients, bufferPool.reversalBuffers)
+    }
+
+    const inverse = transformFunction.transform(
+      blockSpectrum,
+      bufferPool.mdctBuffers
+    )
+    const inverseStart = inverse.length / 4
+    const inverseBuffer = bufferPool.transformBuffers[MDCT_SIZE_LONG]
+    inverseBuffer.fill(0)
+
+    for (let i = 0; i < config.size; i++) {
+      inverseBuffer[i] = inverse[inverseStart + i]
+    }
+
+    const previous = overlapBuffer.slice(
+      config.size * 2 - MDCT_TAIL_WINDOW_SIZE,
+      config.size * 2
+    )
+    const overlap = overlapAdd(
+      previous.slice(0, MDCT_TAIL_WINDOW_SIZE),
+      inverseBuffer.slice(0, MDCT_TAIL_WINDOW_SIZE),
+      WINDOW_SHORT
+    )
+    overlapBuffer.set(overlap, 0)
+
+    for (let i = 0; i < MDCT_TAIL_WINDOW_SIZE; i++) {
+      previous[i] = inverseBuffer[MDCT_TAIL_WINDOW_SIZE + i]
+    }
+
+    const copyLength = bandIndex === 2 ? 240 : 112
+    for (let i = 0; i < copyLength; i++) {
+      overlapBuffer[32 + i] = inverseBuffer[MDCT_TAIL_WINDOW_SIZE + i]
+    }
+
+    for (let i = 0; i < MDCT_TAIL_WINDOW_SIZE; i++) {
+      overlapBuffer[config.size * 2 - MDCT_TAIL_WINDOW_SIZE + i] =
+        inverseBuffer[config.size - MDCT_TAIL_WINDOW_SIZE + i]
+    }
+
+    return overlapBuffer.slice(0, config.size)
+  }
+
+  /**
+   * @param {Float32Array} coefficients
+   * @param {number} bandIndex
+   * @param {Float32Array} overlapBuffer
+   * @param {Object} config
+   * @returns {Float32Array}
+   */
+  function inverseShortBlocks(coefficients, bandIndex, overlapBuffer, config) {
+    const numBlocks = 1 << (config.size === 256 ? 3 : 2)
+    const inverseBuffer = bufferPool.transformBuffers[MDCT_SIZE_LONG]
+    inverseBuffer.fill(0)
+
+    const previous = overlapBuffer.slice(
+      config.size * 2 - MDCT_TAIL_WINDOW_SIZE,
+      config.size * 2
+    )
+    let start = 0
+    let position = 0
+
+    for (let block = 0; block < numBlocks; block++) {
+      let blockSpectrum = coefficients.slice(
+        position,
+        position + MDCT_SHORT_BLOCK_SIZE
+      )
+      if (bandIndex > 0) {
+        blockSpectrum = reverseSpectrum(
+          blockSpectrum,
+          bufferPool.reversalBuffers
+        )
+      }
+
+      const inverse = imdct64.transform(blockSpectrum, bufferPool.mdctBuffers)
+      const inverseStart = inverse.length / 4
+      for (let i = 0; i < MDCT_SHORT_BLOCK_SIZE; i++) {
+        inverseBuffer[start + i] = inverse[inverseStart + i]
+      }
+
+      const overlap = overlapAdd(
+        previous.slice(0, MDCT_TAIL_WINDOW_SIZE),
+        inverseBuffer.slice(start, start + MDCT_TAIL_WINDOW_SIZE),
+        WINDOW_SHORT
+      )
+      overlapBuffer.set(overlap, start)
+
+      for (let i = 0; i < MDCT_TAIL_WINDOW_SIZE; i++) {
+        previous[i] = inverseBuffer[start + MDCT_TAIL_WINDOW_SIZE + i]
+      }
+
+      start += MDCT_SHORT_BLOCK_SIZE
+      position += MDCT_SHORT_BLOCK_SIZE
+    }
+
+    for (let i = 0; i < MDCT_TAIL_WINDOW_SIZE; i++) {
+      overlapBuffer[config.size * 2 - MDCT_TAIL_WINDOW_SIZE + i] =
+        inverseBuffer[config.size - MDCT_TAIL_WINDOW_SIZE + i]
+    }
+
+    return overlapBuffer.slice(0, config.size)
+  }
+
+  /**
+   * @param {object} input
+   * @returns {Array<Float32Array>}
+   */
+  return (input) => {
+    const { coefficients, blockModes } = input
+
+    return MDCT_BAND_CONFIGS.map((config, bandIndex) => {
+      const bandCoefficients = extractBandCoefficients(coefficients, bandIndex)
+      return transformBand(
+        bandCoefficients,
+        bandIndex,
+        blockModes[bandIndex],
+        overlapBuffers[bandIndex],
+        config
+      )
+    })
+  }
+}

package/codec/synthesis/pcm.js

@@ -0,0 +1,50 @@
+/**
+ * Carta1 PCM synthesis application.
+ */
+
+import { synthesizeQmfPair } from '../signal/bands.js'
+import { throwError } from '../utils.js'
+
+/**
+ * Synthesize full-spectrum PCM from frequency bands.
+ *
+ * @param {object} context
+ * @returns {Function}
+ * @throws {Error} If the buffer pool is missing
+ */
+export function synthesizePcm(context) {
+  const bufferPool =
+    context?.bufferPool ?? throwError('synthesizePcm: bufferPool is required')
+  const delays = bufferPool.qmfDelays
+
+  /**
+   * @param {Array<Float32Array>} bands
+   * @returns {Float32Array}
+   */
+  return (bands) => {
+    const delayedHigh = bufferPool.qmfWorkBuffers.highBandDelay[bands[2].length]
+    delayedHigh.set(delays.highBand)
+    delayedHigh.set(bands[2], delays.highBand.length)
+
+    const highBand = delayedHigh.slice(0, bands[0].length * 2)
+    delays.highBand = delayedHigh.slice(bands[0].length * 2)
+
+    const stage2 = synthesizeQmfPair(
+      bands[0],
+      bands[1],
+      delays.midBand,
+      bufferPool.qmfWorkBuffers
+    )
+    delays.midBand = stage2.newDelay
+
+    const stage1 = synthesizeQmfPair(
+      stage2.output,
+      highBand,
+      delays.lowBand,
+      bufferPool.qmfWorkBuffers
+    )
+    delays.lowBand = stage1.newDelay
+
+    return stage1.output
+  }
+}

package/codec/synthesis/stage.js

@@ -0,0 +1,17 @@
+/**
+ * Carta1 synthesis stage.
+ */
+
+import { pipe } from '../utils.js'
+import { synthesizeSpectrum } from './bands.js'
+import { synthesizePcm } from './pcm.js'
+
+/**
+ * Synthesize PCM from the dequantized ATRAC1 spectrum.
+ *
+ * @param {object} context
+ * @returns {Function}
+ */
+export function synthesize(context) {
+  return pipe(context, synthesizeSpectrum, synthesizePcm)
+}

package/codec/utils.js

@@ -1,9 +1,7 @@
 /**
  * Carta1 Audio Codec - Utilities
  *
- * This module provides common utility functions for the ATRAC1 codec including
- * pipeline composition, error handling, and audio stream processing utilities
- * for delay compensation and frame padding.
+ * This module provides common utility functions for the ATRAC1 codec.
  */
 
 /**
@@ -16,55 +14,14 @@ export function throwError(msg) {
 }
 
 /**
- * Creates a pipeline by composing multiple processing stages
- * @param {Object} context - Shared context passed to all stages
- * @param {...Function} stages - Stage functions to compose
- * @returns {Function} Composed pipeline function
- */
-export function pipe(context, ...stages) {
-  const functions = stages.map((stage) => stage(context))
-
-  return (input) => {
-    return functions.reduce((value, fn) => fn(value), input)
-  }
-}
-
-/**
- * Reverses the spectral order of coefficients for mid/high band processing
- *
- * Used in both MDCT and IMDCT stages to handle spectral reversal required
- * by the ATRAC1 format for mid and high frequency bands.
- *
- * @param {Float32Array} spectrum - Input spectrum coefficients
- * @param {Object} reversalBuffers - Pre-allocated buffers for different spectrum sizes
- * @returns {Float32Array} Spectrum with reversed coefficient order
- */
-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
-}
-
-/**
- * Calculates the starting offset for a frequency band in the coefficient array
+ * Compose stateful stage factories once and return the reusable frame path.
  *
- * @param {number} bandIndex - Band index (0=low, 1=mid, 2=high)
- * @returns {number} Starting offset in the 512-sample coefficient array
+ * @param {*} context Shared stage ownership and persistent state.
+ * @param {...Function} stages Ordered stage factories.
+ * @returns {Function} Reusable composed frame operation.
  */
-export function calculateBandOffset(bandIndex) {
-  return bandIndex === 0 ? 0 : bandIndex === 1 ? 128 : 256
-}
-
-/**
- * Extracts coefficients for a specific frequency band from the full coefficient array
- *
- * @param {Float32Array} coefficients - Full 512-sample coefficient array
- * @param {number} bandIndex - Band index (0=low, 1=mid, 2=high)
- * @returns {Float32Array} Subarray containing coefficients for the specified band
- */
-export function extractBandCoefficients(coefficients, bandIndex) {
-  const offsets = [0, 128, 256, 512]
-  return coefficients.subarray(offsets[bandIndex], offsets[bandIndex + 1])
+export function pipe(context, ...stages) {
+  const operations = stages.map((stage) => stage(context))
+  return (input) =>
+    operations.reduce((value, operation) => operation(value), input)
 }