carta1 1.1.9 → 1.2.0

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,49 @@
+/**
+ * Carta1 QMF analysis application.
+ */
+
+import { analyzeQmfPair } from '../signal/bands.js'
+import { throwError } from '../utils.js'
+
+/**
+ * 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.qmfDelays
+
+  /**
+   * @param {Float32Array} pcmSamples
+   * @returns {object}
+   */
+  return (pcmSamples) => {
+    const stage1 = analyzeQmfPair(
+      pcmSamples,
+      delays.lowBand,
+      bufferPool.qmfWorkBuffers
+    )
+    delays.lowBand = stage1.newDelay
+
+    const stage2 = analyzeQmfPair(
+      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] }
+  }
+}

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.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
+}
+
+/**
+ * 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 }
+  }
+}

package/codec/analysis/spectrum.js

@@ -0,0 +1,160 @@
+/**
+ * Carta1 spectral analysis application.
+ */
+
+import {
+  MDCT_OVERLAP_SIZE,
+  MDCT_SHORT_BLOCK_SIZE,
+  MDCT_SIZE_LONG,
+  MDCT_SIZE_MID,
+  MDCT_SIZE_SHORT,
+} from '../core/constants.js'
+import { calculateBandOffset } from '../core/geometry.js'
+import { MDCT_BAND_CONFIGS, WINDOW_SHORT } from '../core/tables.js'
+import {
+  mdct64,
+  mdct256,
+  mdct512,
+  reverseSpectrum,
+} from '../signal/spectrum.js'
+import { throwError } from '../utils.js'
+
+/**
+ * Build the ATRAC1 spectrum from analyzed bands.
+ *
+ * @param {object} context
+ * @returns {Function}
+ * @throws {Error} If the buffer pool is missing
+ */
+export function transformSpectrum(context) {
+  const bufferPool =
+    context?.bufferPool ??
+    throwError('transformSpectrum: bufferPool is required')
+  const overlapBuffers = bufferPool.mdctOverlap
+  const transformFunctions = [mdct256, mdct256, mdct512]
+
+  /**
+   * @param {Float32Array} samples
+   * @param {number} bandIndex
+   * @param {number} blockMode
+   * @param {Float32Array} overlapBuffer
+   * @returns {Float32Array}
+   */
+  function transformBand(samples, bandIndex, blockMode, overlapBuffer) {
+    const config = MDCT_BAND_CONFIGS[bandIndex]
+
+    if (blockMode === 0) {
+      return transformLongBlock(
+        samples,
+        bandIndex,
+        config,
+        transformFunctions[bandIndex],
+        overlapBuffer
+      )
+    }
+
+    return transformShortBlocks(samples, bandIndex, config, overlapBuffer)
+  }
+
+  /**
+   * @param {Float32Array} samples
+   * @param {number} bandIndex
+   * @param {Object} config
+   * @param {Object} transformFunction
+   * @param {Float32Array} overlapBuffer
+   * @returns {Float32Array}
+   */
+  function transformLongBlock(
+    samples,
+    bandIndex,
+    config,
+    transformFunction,
+    overlapBuffer
+  ) {
+    const mdctSize = bandIndex === 2 ? MDCT_SIZE_LONG : MDCT_SIZE_MID
+    const mdctInput = bufferPool.transformBuffers[mdctSize]
+    mdctInput.fill(0)
+    mdctInput.set(overlapBuffer, config.windowStart)
+
+    applyTailWindowing(samples, overlapBuffer, config.size)
+    mdctInput.set(samples, config.windowStart + MDCT_OVERLAP_SIZE)
+
+    let spectrum = transformFunction.transform(
+      mdctInput,
+      bufferPool.mdctBuffers
+    )
+    if (bandIndex > 0) {
+      spectrum = reverseSpectrum(spectrum, bufferPool.reversalBuffers)
+    }
+    return spectrum
+  }
+
+  /**
+   * @param {Float32Array} samples
+   * @param {number} bandIndex
+   * @param {Object} config
+   * @param {Float32Array} overlapBuffer
+   * @returns {Float32Array}
+   */
+  function transformShortBlocks(samples, bandIndex, config, overlapBuffer) {
+    const numBlocks = 1 << (config.size === 256 ? 3 : 2)
+    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
+      )
+      const mdctInput = bufferPool.transformBuffers[MDCT_SIZE_SHORT]
+      mdctInput.fill(0)
+      mdctInput.set(overlapBuffer, 0)
+
+      applyTailWindowing(blockSamples, overlapBuffer, MDCT_SHORT_BLOCK_SIZE)
+      mdctInput.set(blockSamples, MDCT_OVERLAP_SIZE)
+
+      let spectrum = mdct64.transform(mdctInput, bufferPool.mdctBuffers)
+      if (bandIndex > 0) {
+        spectrum = reverseSpectrum(spectrum, bufferPool.reversalBuffers)
+      }
+      output.set(spectrum, blockStart)
+    }
+
+    return output
+  }
+
+  /**
+   * @param {Float32Array} samples
+   * @param {Float32Array} overlapBuffer
+   * @param {number} blockSize
+   */
+  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]
+    }
+  }
+
+  /**
+   * @param {object} input
+   * @returns {object}
+   */
+  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]
+      )
+      coefficients.set(transformed, calculateBandOffset(bandIndex))
+    })
+
+    return { bands, coefficients, blockModes, originalFrame }
+  }
+}

package/codec/analysis/stage.js

@@ -0,0 +1,32 @@
+/**
+ * Carta1 analysis stage.
+ */
+
+import { pipe } from '../utils.js'
+import { analyzeBands } from './bands.js'
+import { selectBlocks } from './blocks.js'
+import { transformSpectrum } from './spectrum.js'
+
+/**
+ * Analyze a PCM frame in the ATRAC1 signal domain.
+ *
+ * @param {object} context
+ * @returns {Function}
+ */
+export function analyze(context) {
+  const analyzeFrame = pipe(
+    context,
+    analyzeBands,
+    selectBlocks,
+    transformSpectrum
+  )
+
+  /**
+   * @param {Float32Array} pcmSamples
+   * @returns {object}
+   */
+  return (pcmSamples) => {
+    const { coefficients, blockModes } = analyzeFrame(pcmSamples)
+    return { coefficients, blockModes }
+  }
+}

package/codec/{browser/interface.js → boundary/browser.js}

@@ -1,5 +1,5 @@
 /**
- * Carta1 Worker Interface - Client-side API
+ * Carta1 browser worker boundary.
  *
  * Provides a clean async interface for encoding and decoding ATRAC1 audio
  * using Web Workers for non-blocking operation.

package/codec/boundary/container.js

@@ -0,0 +1,96 @@
+/**
+ * Carta1 AEA container boundary.
+ */
+
+import {
+  AEA_CHANNEL_COUNT_OFFSET,
+  AEA_FRAME_COUNT_OFFSET,
+  AEA_HEADER_SIZE,
+  AEA_PRIMING_SAMPLE_COUNT_OFFSET,
+  AEA_SOURCE_SAMPLE_COUNT_OFFSET,
+  AEA_TITLE_OFFSET,
+  AEA_TITLE_SIZE,
+  STREAM_PRIMING_SAMPLES,
+} from '../core/constants.js'
+import { AEA_MAGIC } from '../core/tables.js'
+
+/**
+ * AEA file-format handler.
+ */
+export class AeaFile {
+  /**
+   * Create an AEA header.
+   *
+   * @param {string} [title='']
+   * @param {number} [frameCount=0]
+   * @param {number} [channelCount=1]
+   * @param {number} [sampleCount=0]
+   * @param {number} [primingSampleCount=STREAM_PRIMING_SAMPLES]
+   * @returns {Uint8Array}
+   */
+  static createHeader(
+    title = '',
+    frameCount = 0,
+    channelCount = 1,
+    sampleCount = 0,
+    primingSampleCount = STREAM_PRIMING_SAMPLES
+  ) {
+    const header = new Uint8Array(AEA_HEADER_SIZE)
+    const view = new DataView(header.buffer)
+    header.set(AEA_MAGIC, 0)
+
+    const titleBytes = new TextEncoder().encode(title)
+    header.set(
+      titleBytes.subarray(0, Math.min(titleBytes.length, AEA_TITLE_SIZE - 1)),
+      AEA_TITLE_OFFSET
+    )
+    view.setUint32(AEA_FRAME_COUNT_OFFSET, frameCount, true)
+    header[AEA_CHANNEL_COUNT_OFFSET] = channelCount
+    view.setUint32(
+      AEA_PRIMING_SAMPLE_COUNT_OFFSET,
+      primingSampleCount >>> 0,
+      true
+    )
+    view.setUint32(AEA_SOURCE_SAMPLE_COUNT_OFFSET, sampleCount >>> 0, true)
+    return header
+  }
+
+  /**
+   * Parse an AEA header.
+   *
+   * @param {Uint8Array} header
+   * @returns {object} Container metadata.
+   * @throws {Error} If the header is invalid
+   */
+  static parseHeader(header) {
+    if (header.length !== AEA_HEADER_SIZE) {
+      throw new Error(`Header must be ${AEA_HEADER_SIZE} bytes`)
+    }
+
+    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
+    )
+    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)
+    )
+
+    return {
+      title,
+      frameCount: view.getUint32(AEA_FRAME_COUNT_OFFSET, true),
+      channelCount: header[AEA_CHANNEL_COUNT_OFFSET],
+      primingSampleCount: view.getUint32(AEA_PRIMING_SAMPLE_COUNT_OFFSET, true),
+      sampleCount: view.getUint32(AEA_SOURCE_SAMPLE_COUNT_OFFSET, true),
+    }
+  }
+}