carta1 1.0.0

package/codec/io/serialization.js

@@ -0,0 +1,254 @@
+/**
+ * Carta1 Audio Codec - Serialization Module
+ *
+ * Handles serialization and deserialization of ATRAC1 audio frames and AEA file format.
+ * Provides functions for packing encoded frame data into binary format and unpacking
+ * it back into structured data for processing.
+ *
+ * The module manages:
+ * - Frame data serialization/deserialization with proper bit packing
+ * - AEA file header creation and parsing
+ * - Binary format compliance for ATRAC1 specification
+ */
+
+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 { packBits, unpackBits, unpackSignedBits } from '../core/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.blockSizeMode - Block size mode 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
+ * @returns {Uint8Array} Serialized frame data buffer
+ */
+export function serializeFrame(frameData) {
+  const buffer = new Uint8Array(SOUND_UNIT_SIZE)
+  const view = new DataView(buffer.buffer)
+
+  // Pack header (16 bits)
+  const bfuIndex = BFU_AMOUNTS.indexOf(frameData.nBfu)
+  const header =
+    ((2 - frameData.blockSizeMode[0]) << 14) |
+    ((2 - frameData.blockSizeMode[1]) << 12) |
+    ((3 - frameData.blockSizeMode[2]) << 10) |
+    (bfuIndex << 5)
+
+  view.setUint16(0, header, false)
+  let bitPosition = FRAME_HEADER_BITS
+
+  // Pack word lengths (4 bits each)
+  for (let i = 0; i < frameData.nBfu; i++) {
+    packBits(
+      buffer,
+      bitPosition,
+      frameData.wordLengthIndices[i],
+      FRAME_WORD_LENGTH_BITS
+    )
+    bitPosition += FRAME_WORD_LENGTH_BITS
+  }
+
+  // Pack scale factors (6 bits each)
+  for (let i = 0; i < frameData.nBfu; i++) {
+    packBits(
+      buffer,
+      bitPosition,
+      frameData.scaleFactorIndices[i],
+      FRAME_SCALE_FACTOR_BITS
+    )
+    bitPosition += FRAME_SCALE_FACTOR_BITS
+  }
+
+  // Pack quantized coefficients
+  for (let i = 0; i < frameData.nBfu; i++) {
+    const bitsPerSample = WORD_LENGTH_BITS[frameData.wordLengthIndices[i]]
+    if (bitsPerSample > 0) {
+      const coefficients = frameData.quantizedCoefficients[i]
+      for (const coefficient of coefficients) {
+        const value =
+          coefficient < 0 ? coefficient + (1 << bitsPerSample) : coefficient
+        packBits(buffer, bitPosition, value, bitsPerSample)
+        bitPosition += bitsPerSample
+      }
+    }
+  }
+
+  // Zero padding at end
+  buffer[SOUND_UNIT_SIZE - 3] = 0
+  buffer[SOUND_UNIT_SIZE - 2] = 0
+  buffer[SOUND_UNIT_SIZE - 1] = 0
+
+  return buffer
+}
+
+/**
+ * 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.blockSizeMode - Block size mode 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
+ * @throws {Error} If buffer size is invalid
+ */
+export function deserializeFrame(buffer) {
+  if (buffer.length !== SOUND_UNIT_SIZE) {
+    throw new Error(`Frame must be ${SOUND_UNIT_SIZE} bytes`)
+  }
+
+  const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength)
+
+  // Unpack header
+  const header = view.getUint16(0, false)
+  const blockSizeMode = [
+    2 - ((header >> 14) & 3),
+    2 - ((header >> 12) & 3),
+    3 - ((header >> 10) & 3),
+  ]
+  const bfuIndex = (header >> 5) & 7
+  const nBfu = BFU_AMOUNTS[bfuIndex]
+
+  let bitPosition = FRAME_HEADER_BITS
+
+  // Unpack word lengths
+  const wordLengthIndices = new Int32Array(nBfu)
+  for (let i = 0; i < nBfu; i++) {
+    wordLengthIndices[i] = unpackBits(
+      buffer,
+      bitPosition,
+      FRAME_WORD_LENGTH_BITS
+    )
+    bitPosition += FRAME_WORD_LENGTH_BITS
+  }
+
+  // Unpack scale factors
+  const scaleFactorIndices = new Int32Array(nBfu)
+  for (let i = 0; i < nBfu; i++) {
+    scaleFactorIndices[i] = unpackBits(
+      buffer,
+      bitPosition,
+      FRAME_SCALE_FACTOR_BITS
+    )
+    bitPosition += FRAME_SCALE_FACTOR_BITS
+  }
+
+  // Unpack coefficients
+  const quantizedCoefficients = []
+  for (let i = 0; i < nBfu; i++) {
+    const bitsPerSample = WORD_LENGTH_BITS[wordLengthIndices[i]]
+    const bfuSize = SPECS_PER_BFU[i]
+    const coefficients = new Int32Array(bfuSize)
+
+    if (bitsPerSample > 0) {
+      for (let j = 0; j < bfuSize; j++) {
+        coefficients[j] = unpackSignedBits(buffer, bitPosition, bitsPerSample)
+        bitPosition += bitsPerSample
+      }
+    }
+
+    quantizedCoefficients.push(coefficients)
+  }
+
+  return {
+    nBfu,
+    scaleFactorIndices,
+    wordLengthIndices,
+    quantizedCoefficients,
+    blockSizeMode,
+  }
+}
+
+/**
+ * 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/pipeline/decoder.js

@@ -0,0 +1,278 @@
+/**
+ * Carta1 Audio Codec - Decoding Pipeline
+ *
+ * The decoding pipeline transforms ATRAC1 compressed format back into PCM audio samples
+ * through a series of processing stages:
+ *
+ * 1. Dequantization: Reconstructs MDCT coefficients from quantized data using scale factors
+ * 2. Inverse MDCT: Applies Inverse Modified Discrete Cosine Transform to frequency bands
+ * 3. QMF Synthesis: Reconstructs full-spectrum audio using quadrature mirror filters
+ *
+ * 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 decoding options.
+ */
+
+import { pipe, throwError } from '../utils.js'
+import { qmfSynthesis } from '../transforms/qmf.js'
+import { imdct64, imdct256, imdct512, overlapAdd } from '../transforms/mdct.js'
+import { dequantize } from '../coding/quantization.js'
+import { BufferPool } from '../core/buffers.js'
+import {
+  BFU_BAND_BOUNDARIES,
+  BFU_START_LONG,
+  BFU_START_SHORT,
+  WORD_LENGTH_BITS,
+  WINDOW_SHORT,
+  MDCT_SIZE_LONG,
+} from '../core/constants.js'
+
+/**
+ * Dequantization Stage - Reconstructs MDCT coefficients from quantized data
+ *
+ * Reverses the quantization process by:
+ * - Reconstructing coefficient values using scale factors and word lengths
+ * - Organizing coefficients back into Block Floating Units (BFUs)
+ * - Preparing coefficient array for inverse MDCT transform
+ *
+ * Uses the same BFU organization as the encoder but reconstructs the original
+ * coefficient values from the quantized representation.
+ *
+ * @returns {Function} Stage function that processes quantized frame data
+ * @throws {Error} If bufferPool is not provided in context
+ */
+function dequantizationStage() {
+  /**
+   * Reconstruct MDCT coefficients from quantized data
+   * @param {Object} frameData - Quantized frame data
+   * @param {number} frameData.nBfu - Number of active BFUs
+   * @param {Int32Array} frameData.scaleFactorIndices - Scale factor indices for each BFU
+   * @param {Int32Array} frameData.wordLengthIndices - Word length indices for each BFU
+   * @param {Array<Int32Array>} frameData.quantizedCoefficients - Quantized coefficient data
+   * @param {Array<number>} frameData.blockSizeMode - Block size mode for each band
+   * @returns {Array} Dequantization results [coefficients, blockModes]
+   * @returns {Float32Array} returns[0] - Reconstructed MDCT coefficients (512 samples)
+   * @returns {Array<number>} returns[1] - Block mode indices for each band
+   */
+  return (frameData) => {
+    const coefficients = new Float32Array(512)
+    const {
+      nBfu,
+      scaleFactorIndices,
+      wordLengthIndices,
+      quantizedCoefficients,
+      blockSizeMode,
+    } = frameData
+
+    for (let bfu = 0; bfu < nBfu; bfu++) {
+      const bitsPerSample = WORD_LENGTH_BITS[wordLengthIndices[bfu]]
+
+      let band = 0
+      if (bfu >= BFU_BAND_BOUNDARIES[0]) band = 1
+      if (bfu >= BFU_BAND_BOUNDARIES[1]) band = 2
+
+      const isLongBlock = blockSizeMode[band] === 0
+      const position = isLongBlock ? BFU_START_LONG[bfu] : BFU_START_SHORT[bfu]
+
+      if (bitsPerSample > 0) {
+        const quantized = quantizedCoefficients[bfu]
+        const dequantized = dequantize(
+          quantized,
+          scaleFactorIndices[bfu],
+          bitsPerSample
+        )
+        coefficients.set(dequantized, position)
+      }
+    }
+
+    return [coefficients, blockSizeMode]
+  }
+}
+
+/**
+ * Inverse MDCT Stage - Transforms frequency coefficients back to time domain
+ *
+ * Applies Inverse Modified Discrete Cosine Transform to reconstruct time-domain
+ * samples from frequency coefficients. The transform size depends on block modes:
+ * - Long blocks: 512/256 samples for steady-state signals
+ * - Short blocks: 64 samples for transient signals
+ *
+ * Applies windowing and overlap-add processing to prevent blocking artifacts.
+ * Mid and high bands are spectrally unreversed from 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 dequantization results
+ * @throws {Error} If bufferPool is not provided in context
+ */
+function imdctStage(context) {
+  const bufferPool =
+    context?.bufferPool ?? throwError('imdctStage: bufferPool is required')
+  const overlapBuffers = bufferPool.imdctOverlap
+
+  /**
+   * Transform coefficients back to time domain using inverse MDCT
+   * @param {Array} input - Dequantization results
+   * @param {Float32Array} input[0] - MDCT coefficients (512 samples)
+   * @param {Array<number>} input[1] - Block mode indices for each band
+   * @returns {Array<Float32Array>} Three reconstructed frequency bands [low, mid, high]
+   */
+  return (input) => {
+    const [coefficients, blockModes] = input
+    const bands = []
+
+    const bandCoeffs = [
+      coefficients.subarray(0, 128),
+      coefficients.subarray(128, 256),
+      coefficients.subarray(256, 512),
+    ]
+
+    for (let band = 0; band < 3; band++) {
+      const bandSize = band === 2 ? 256 : 128
+      const numBlocks = 1 << blockModes[band]
+      const blockSize = numBlocks === 1 ? bandSize : 32
+
+      const imdctFunc =
+        numBlocks === 1 ? (band === 2 ? imdct512 : imdct256) : imdct64
+
+      const invBuf = bufferPool.transformBuffers[MDCT_SIZE_LONG]
+      invBuf.fill(0)
+      const dstBuf = overlapBuffers[band]
+      const prevBuf = dstBuf.slice(bandSize * 2 - 16, bandSize * 2)
+
+      let start = 0
+      let pos = 0
+
+      for (let block = 0; block < numBlocks; block++) {
+        let blockSpecs = bandCoeffs[band].slice(pos, pos + blockSize)
+
+        // Reverse spectral reversal for mid and high bands
+        if (band > 0) {
+          const reversed = bufferPool.reversalBuffers[blockSpecs.length]
+          for (let i = 0; i < blockSpecs.length; i++) {
+            reversed[i] = blockSpecs[blockSpecs.length - 1 - i]
+          }
+          blockSpecs = reversed
+        }
+
+        const inv = imdctFunc.transform(blockSpecs, bufferPool.mdctBuffers)
+        const invStart = inv.length / 4
+
+        for (let i = 0; i < blockSize; i++) {
+          invBuf[start + i] = inv[invStart + i]
+        }
+
+        const dstPart = overlapAdd(
+          prevBuf.slice(0, 16),
+          invBuf.slice(start, start + 16),
+          WINDOW_SHORT
+        )
+
+        dstBuf.set(dstPart, start)
+
+        for (let i = 0; i < 16; i++) {
+          prevBuf[i] = invBuf[start + 16 + i]
+        }
+
+        start += blockSize
+        pos += blockSize
+      }
+
+      if (numBlocks === 1) {
+        const copyLen = band === 2 ? 240 : 112
+        for (let i = 0; i < copyLen; i++) {
+          dstBuf[32 + i] = invBuf[16 + i]
+        }
+      }
+
+      for (let i = 0; i < 16; i++) {
+        dstBuf[bandSize * 2 - 16 + i] = invBuf[bandSize - 16 + i]
+      }
+
+      bands.push(dstBuf.slice(0, bandSize))
+    }
+
+    return bands
+  }
+}
+
+/**
+ * QMF Synthesis Stage - Reconstructs full-spectrum audio from frequency bands
+ *
+ * Performs two-stage QMF synthesis to reconstruct the full-spectrum signal
+ * from three frequency 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
+ *
+ * This is the inverse operation of the QMF analysis performed during encoding,
+ * combining the separate frequency bands back into a single wideband signal.
+ *
+ * @param {Object} context - Pipeline context containing bufferPool
+ * @param {BufferPool} context.bufferPool - Shared buffer pool for efficient memory management
+ * @returns {Function} Stage function that processes inverse MDCT results
+ * @throws {Error} If bufferPool is not provided in context
+ */
+function qmfSynthesisStage(context) {
+  const bufferPool =
+    context?.bufferPool ??
+    throwError('qmfSynthesisStage: bufferPool is required')
+  const delays = bufferPool.qmfDelays
+
+  /**
+   * Reconstruct full-spectrum PCM samples from frequency bands
+   * @param {Array<Float32Array>} bands - Three frequency bands [low, mid, high]
+   * @returns {Float32Array} Reconstructed PCM samples
+   */
+  return (bands) => {
+    // Apply high band delay compensation
+    const delayedHigh = bufferPool.qmfWorkBuffers.highBandDelay[bands[2].length]
+    delayedHigh.set(delays.highBand)
+    delayedHigh.set(bands[2])
+
+    const highBand = delayedHigh.slice(0, bands[0].length * 2)
+    delays.highBand = delayedHigh.slice(bands[0].length * 2)
+
+    // Second stage synthesis: combine low and mid bands
+    const stage2 = qmfSynthesis(
+      bands[0],
+      bands[1],
+      delays.midBand,
+      bufferPool.qmfWorkBuffers
+    )
+    delays.midBand = stage2.newDelay
+
+    // First stage synthesis: combine result with high band
+    const stage1 = qmfSynthesis(
+      stage2.output,
+      highBand,
+      delays.lowBand,
+      bufferPool.qmfWorkBuffers
+    )
+    delays.lowBand = stage1.newDelay
+
+    return stage1.output
+  }
+}
+
+/**
+ * Create ATRAC1 decoding pipeline
+ *
+ * Constructs a complete decoding pipeline that transforms ATRAC1 compressed format
+ * back into PCM audio samples. The pipeline processes quantized data through
+ * dequantization, inverse MDCT transform, and QMF synthesis.
+ *
+ * The returned function can be called repeatedly to decode audio frames,
+ * maintaining state through the shared buffer pool for efficient processing.
+ *
+ * @param {BufferPool} [bufferPool=new BufferPool()] - Shared buffer pool for state
+ * @returns {Function} Decoding pipeline function that processes quantized frame data
+ *
+ * @example
+ * const decoder = decode(new BufferPool())
+ * const result = decoder(quantizedFrame) // Returns reconstructed PCM samples
+ */
+export function decode(bufferPool = new BufferPool()) {
+  const context = { bufferPool }
+  return pipe(context, dequantizationStage, imdctStage, qmfSynthesisStage)
+}