carta1 1.2.0 → 1.4.0

package/README.md

@@ -58,7 +58,7 @@ signed 16-bit PCM WAVE output.
 | `-j, --json`          | Write AEA metadata and frame structure as JSON.      |
 | `-q, --quiet`         | Suppress normal output and progress.                 |
 | `-f, --force`         | Overwrite an existing output file.                   |
-| `-t, --title <title>` | Set the AEA title while encoding.                    |
+| `-t, --title <title>` | Set a UTF-8 AEA title (up to 255 encoded bytes).     |
 | `-b, --bias <value>`  | Set the bit-allocation bias; defaults to `1.0`.      |
 | `-m, --modes <modes>` | Fix low, mid, and high block modes, such as `0,0,0`. |
 | `-V, --version`       | Print the Carta1 version.                            |

package/bin/cli.js

@@ -21,14 +21,13 @@ import wav from 'wav'
 
 import { AudioProcessor } from '../codec/boundary/processor.js'
 import { AeaReader } from '../codec/boundary/reader.js'
-import { AeaFile } from '../codec/boundary/container.js'
+import { AeaFile, validateAeaTitle } from '../codec/boundary/container.js'
 import { deserializeFrame } from '../codec/syntax/frame.js'
 import { EncoderOptions } from '../codec/core/options.js'
 import {
   SAMPLE_RATE,
   SAMPLES_PER_FRAME,
   BITRATE_PER_CHANNEL,
-  AEA_TITLE_SIZE,
   AEA_HEADER_SIZE,
   SOUND_UNIT_SIZE,
 } from '../codec/core/constants.js'
@@ -48,7 +47,7 @@ function formatTime(seconds) {
 }
 
 /**
- * Validate AEA title for length and ASCII encoding
+ * Validate an AEA title for its fixed-width UTF-8 field.
  *
  * @param {string} title - Title to validate
  * @returns {Object} Validation result
@@ -56,31 +55,7 @@ function formatTime(seconds) {
  * @returns {string} [returns.error] - Error message if invalid
  */
 function validateTitle(title) {
-  if (!title) {
-    return { valid: true }
-  }
-
-  // Check ASCII encoding
-  for (let i = 0; i < title.length; i++) {
-    const charCode = title.charCodeAt(i)
-    if (charCode > 127) {
-      return {
-        valid: false,
-        error: `Title contains non-ASCII character at position ${i}: "${title[i]}"`,
-      }
-    }
-  }
-
-  // Check length (AEA_TITLE_SIZE includes null terminator)
-  const maxLength = AEA_TITLE_SIZE - 1
-  if (title.length > maxLength) {
-    return {
-      valid: false,
-      error: `Title is too long (${title.length} chars). Maximum allowed: ${maxLength} characters`,
-    }
-  }
-
-  return { valid: true }
+  return validateAeaTitle(title)
 }
 
 /**
@@ -703,7 +678,7 @@ async function main() {
     .option('-f, --force', 'Overwrite output file if it exists')
     .option(
       '-t, --title <title>',
-      'Custom title for AEA file metadata (encoding only)'
+      'Custom UTF-8 title for AEA file metadata (encoding only)'
     )
     .option(
       '-b, --bias <value>',

package/codec/analysis/bands.js

@@ -2,9 +2,34 @@
  * Carta1 QMF analysis application.
  */
 
-import { analyzeQmfPair } from '../signal/bands.js'
+import { QMF_ANALYSIS_DELAY_SAMPLES } from '../core/constants.js'
+import { analyzeQmf } from '../signal/qmf.js'
 import { throwError } from '../utils.js'
 
+/**
+ * Split one sample row through a two-band configurable QMF stage.
+ *
+ * @param {Float32Array} input
+ * @param {Float32Array} delay
+ * @param {object} scratch
+ * @returns {Float32Array[]}
+ */
+function analyzePair(input, delay, scratch) {
+  const window =
+    scratch.analysisWindows[input.length] ??
+    throwError(`QMF analysis window for ${input.length} samples is required`)
+  window.set(delay)
+  window.set(input, delay.length)
+
+  const sampleCount = input.length / 2
+  const bands = [new Float32Array(sampleCount), new Float32Array(sampleCount)]
+  analyzeQmf(window, bands, scratch)
+  delay.set(
+    window.subarray(input.length, input.length + QMF_ANALYSIS_DELAY_SAMPLES)
+  )
+  return bands
+}
+
 /**
  * Split PCM into the three ATRAC1 frequency bands.
  *
@@ -15,35 +40,29 @@ import { throwError } from '../utils.js'
 export function analyzeBands(context) {
   const bufferPool =
     context?.bufferPool ?? throwError('analyzeBands: bufferPool is required')
-  const delays = bufferPool.qmfDelays
+  const delays = bufferPool.qmfAnalysisDelays
+  const scratch = bufferPool.qmfScratch
 
   /**
    * @param {Float32Array} pcmSamples
    * @returns {object}
    */
   return (pcmSamples) => {
-    const stage1 = analyzeQmfPair(
-      pcmSamples,
-      delays.lowBand,
-      bufferPool.qmfWorkBuffers
-    )
-    delays.lowBand = stage1.newDelay
+    const stage1 = analyzePair(pcmSamples, delays.lowBand, scratch)
+    const stage2 = analyzePair(stage1[0], delays.midBand, scratch)
 
-    const stage2 = analyzeQmfPair(
-      stage1.lowBand,
-      delays.midBand,
-      bufferPool.qmfWorkBuffers
-    )
-    delays.midBand = stage2.newDelay
+    const delayedHigh = scratch.highBandWindows[stage1[1].length]
+    delayedHigh.set(bufferPool.qmfHighBandDelay)
+    delayedHigh.set(stage1[1], bufferPool.qmfHighBandDelay.length)
 
-    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)
+    const highBand = delayedHigh.slice(0, stage1[1].length)
+    bufferPool.qmfHighBandDelay.set(
+      delayedHigh.subarray(
+        stage1[1].length,
+        stage1[1].length + bufferPool.qmfHighBandDelay.length
+      )
+    )
 
-    return { bands: [stage2.lowBand, stage2.highBand, highBand] }
+    return { bands: [stage2[0], stage2[1], highBand] }
   }
 }

package/codec/analysis/blocks.js

@@ -196,7 +196,7 @@ export function performFFT(samples, fftSize) {
   real.set(samples.subarray(0, copyLen))
 
   // Perform FFT
-  FFT.fft(real, imag)
+  FFT.transform(real, imag)
 
   // Calculate magnitude spectrum for positive frequencies
   const magnitude = new Float32Array(fftSize / 2)

package/codec/analysis/spectrum.js

@@ -11,14 +11,14 @@ import {
 } 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 { MDCT } from '../signal/mdct.js'
+import { reverseSpectrum } from '../signal/order.js'
 import { throwError } from '../utils.js'
 
+const shortMdct = new MDCT(MDCT_SIZE_SHORT, 0.5)
+const middleMdct = new MDCT(MDCT_SIZE_MID, 0.5)
+const longMdct = new MDCT(MDCT_SIZE_LONG, 1)
+
 /**
  * Build the ATRAC1 spectrum from analyzed bands.
  *
@@ -31,7 +31,7 @@ export function transformSpectrum(context) {
     context?.bufferPool ??
     throwError('transformSpectrum: bufferPool is required')
   const overlapBuffers = bufferPool.mdctOverlap
-  const transformFunctions = [mdct256, mdct256, mdct512]
+  const transformFunctions = [middleMdct, middleMdct, longMdct]
 
   /**
    * @param {Float32Array} samples
@@ -113,7 +113,7 @@ export function transformSpectrum(context) {
       applyTailWindowing(blockSamples, overlapBuffer, MDCT_SHORT_BLOCK_SIZE)
       mdctInput.set(blockSamples, MDCT_OVERLAP_SIZE)
 
-      let spectrum = mdct64.transform(mdctInput, bufferPool.mdctBuffers)
+      let spectrum = shortMdct.transform(mdctInput, bufferPool.mdctBuffers)
       if (bandIndex > 0) {
         spectrum = reverseSpectrum(spectrum, bufferPool.reversalBuffers)
       }

package/codec/boundary/container.js

@@ -14,6 +14,29 @@ import {
 } from '../core/constants.js'
 import { AEA_MAGIC } from '../core/tables.js'
 
+const UTF8_ENCODER = new TextEncoder()
+const UTF8_DECODER = new TextDecoder()
+
+/**
+ * Validate a title for the fixed-width AEA title field.
+ *
+ * @param {string} title
+ * @returns {{valid: boolean, error?: string}}
+ */
+export function validateAeaTitle(title) {
+  const byteLength = UTF8_ENCODER.encode(title).length
+  const maxByteLength = AEA_TITLE_SIZE - 1
+
+  if (byteLength > maxByteLength) {
+    return {
+      valid: false,
+      error: `Title is too long (${byteLength} UTF-8 bytes). Maximum allowed: ${maxByteLength} bytes`,
+    }
+  }
+
+  return { valid: true }
+}
+
 /**
  * AEA file-format handler.
  */
@@ -39,10 +62,9 @@ export class AeaFile {
     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
+    UTF8_ENCODER.encodeInto(
+      title,
+      header.subarray(AEA_TITLE_OFFSET, AEA_TITLE_OFFSET + AEA_TITLE_SIZE - 1)
     )
     view.setUint32(AEA_FRAME_COUNT_OFFSET, frameCount, true)
     header[AEA_CHANNEL_COUNT_OFFSET] = channelCount
@@ -81,7 +103,7 @@ export class AeaFile {
     const titleEnd = header.indexOf(0, AEA_TITLE_OFFSET)
     const titleLength =
       titleEnd === -1 ? AEA_TITLE_SIZE : titleEnd - AEA_TITLE_OFFSET
-    const title = new TextDecoder().decode(
+    const title = UTF8_DECODER.decode(
       header.subarray(AEA_TITLE_OFFSET, AEA_TITLE_OFFSET + titleLength)
     )
 

package/codec/core/constants.js

@@ -34,8 +34,17 @@ export const MDCT_SHORT_BLOCK_SIZE = 32
 export const MDCT_OVERLAP_SIZE = 32
 export const MDCT_TAIL_WINDOW_SIZE = 16
 
+export const QMF_BANDS = 2
 export const QMF_TAPS = 48
-export const QMF_DELAY = 46
+export const QMF_ANALYSIS_START_SAMPLE = 0
+export const QMF_ANALYSIS_STEP_SAMPLES = QMF_BANDS
+export const QMF_ANALYSIS_WINDOW_SAMPLES = QMF_TAPS
+export const QMF_ANALYSIS_MODULATION_SCALE = 1
+export const QMF_ANALYSIS_TERMS = 24
+export const QMF_ANALYSIS_DELAY_SAMPLES = QMF_TAPS - QMF_BANDS
+export const QMF_SYNTHESIS_DELAY_ROWS = 24
+export const QMF_SYNTHESIS_TERMS = 24
+export const QMF_SYNTHESIS_DELAY_SAMPLES = QMF_BANDS * QMF_SYNTHESIS_DELAY_ROWS
 export const QMF_HIGH_BAND_DELAY = 39
 
 export const FFT_SIZE_LOW = 128

package/codec/core/tables.js

@@ -2,7 +2,14 @@
  * Stable ATRAC1 geometry, signal, allocation, and quantization tables.
  */
 
-import { MAX_WORD_LENGTH_INDEX, QMF_TAPS } from './constants.js'
+import {
+  MAX_WORD_LENGTH_INDEX,
+  QMF_ANALYSIS_TERMS,
+  QMF_BANDS,
+  QMF_SYNTHESIS_DELAY_ROWS,
+  QMF_SYNTHESIS_TERMS,
+  QMF_TAPS,
+} from './constants.js'
 
 export const AEA_MAGIC = new Uint8Array([0x00, 0x08, 0x00, 0x00])
 
@@ -70,6 +77,97 @@ export const QMF_ODD = (() => {
   return odd
 })()
 
+/** Sample positions read by each component of the configurable QMF analysis. */
+export const QMF_ANALYSIS_SAMPLE_OFFSETS = (() => {
+  const offsets = new Uint8Array(QMF_BANDS * QMF_ANALYSIS_TERMS)
+  for (let term = 0; term < QMF_ANALYSIS_TERMS; term++) {
+    offsets[term] = QMF_TAPS - 1 - term * QMF_BANDS
+    offsets[QMF_ANALYSIS_TERMS + term] = QMF_TAPS - QMF_BANDS - term * QMF_BANDS
+  }
+  return offsets
+})()
+
+/** Prototype-filter coefficients in component-major QMF analysis order. */
+export const QMF_ANALYSIS_FILTER_COEFFICIENTS = (() => {
+  const coefficients = new Float32Array(QMF_BANDS * QMF_ANALYSIS_TERMS)
+  coefficients.set(QMF_EVEN)
+  coefficients.set(QMF_ODD, QMF_ANALYSIS_TERMS)
+  return coefficients
+})()
+
+/** Dense modulation applied after Carta1 QMF analysis filtering. */
+export const QMF_ANALYSIS_MODULATION_COEFFICIENTS = new Float32Array([
+  1, 1, 1, -1,
+])
+
+/* eslint-disable no-loss-of-precision -- Float32Array applies the intended float32 rounding. */
+
+/** Reference factors used by the optimized sixteen-band modulation path. */
+export const QMF_ANALYSIS_PI_OVER_8_BUTTERFLY_SCALES = new Float32Array([
+  1.8477590084075928, 0.7653668522834778, 1.8477590084075928,
+  0.7653668522834778,
+])
+
+/** Reference half-angle factors used by sixteen-band modulation. */
+export const QMF_ANALYSIS_HALF_BUTTERFLY_SCALES = new Float32Array([
+  0.7071067690849304, 0.2071067839860916, 1.2071068286895752,
+])
+
+/** Reference odd pi/32 cosines used by sixteen-band modulation. */
+export const QMF_ANALYSIS_ODD_PI_OVER_32_COSINES = new Float32Array([
+  1.990369439125061, 1.913880705833435, 1.7638425827026367, 1.5460208654403687,
+  1.2687865495681763, 0.9427934885025024, 0.5805693864822388,
+  0.1960342824459076,
+])
+
+/** Reference odd pi/16 cosines used by sixteen-band modulation. */
+export const QMF_ANALYSIS_ODD_PI_OVER_16_COSINES = new Float32Array([
+  1.9615705013275146, 1.662939190864563, 1.111140489578247, 0.39018064737319946,
+])
+
+/** Reference odd pi/64 cosines used by sixteen-band modulation. */
+export const QMF_ANALYSIS_ODD_PI_OVER_64_COSINES = new Float32Array([
+  1.9975908994674683, 1.9783530235290527, 1.9400625228881836,
+  1.8830881118774414, 1.807978630065918, 1.7154572010040283, 1.606415033340454,
+  1.4819022417068481, 1.3431179523468018, 1.1913986206054688,
+  1.0282055139541626, 0.8551101684570312, 0.6737797260284424,
+  0.48596036434173584, 0.2934609651565552, 0.09813535213470459,
+])
+
+/* eslint-enable no-loss-of-precision */
+
+/** Delay-row offsets read by each sample of configurable QMF synthesis. */
+export const QMF_SYNTHESIS_DELAY_ROW_OFFSETS = (() => {
+  const offsets = new Uint8Array(QMF_BANDS * QMF_SYNTHESIS_TERMS)
+  for (let sample = 0; sample < QMF_BANDS; sample++) {
+    const sampleOffset = sample * QMF_SYNTHESIS_TERMS
+    for (let term = 0; term < QMF_SYNTHESIS_TERMS; term++) {
+      offsets[sampleOffset + term] = QMF_SYNTHESIS_DELAY_ROWS - 1 - term
+    }
+  }
+  return offsets
+})()
+
+/** Delay components read by each sample of configurable QMF synthesis. */
+export const QMF_SYNTHESIS_DELAY_COMPONENTS = (() => {
+  const components = new Uint8Array(QMF_BANDS * QMF_SYNTHESIS_TERMS)
+  components.fill(1, 0, QMF_SYNTHESIS_TERMS)
+  return components
+})()
+
+/** Prototype-filter coefficients in output-sample-major QMF synthesis order. */
+export const QMF_SYNTHESIS_FILTER_COEFFICIENTS = (() => {
+  const coefficients = new Float64Array(QMF_BANDS * QMF_SYNTHESIS_TERMS)
+  coefficients.set(QMF_ODD)
+  coefficients.set(QMF_EVEN, QMF_SYNTHESIS_TERMS)
+  return coefficients
+})()
+
+/** Dense modulation applied before Carta1 QMF synthesis filtering. */
+export const QMF_SYNTHESIS_MODULATION_COEFFICIENTS = new Float64Array([
+  0.5, 0.5, 0.5, -0.5,
+])
+
 export const MDCT_BAND_CONFIGS = [
   { size: 128, windowStart: 48 },
   { size: 128, windowStart: 48 },

package/codec/dequantization.js

@@ -8,7 +8,7 @@ import {
   BFU_START_SHORT,
   WORD_LENGTH_BITS,
 } from './core/tables.js'
-import { dequantize as dequantizeCoefficient } from './quantization/spectrum.js'
+import * as spectrumQuantization from './quantization/spectrum.js'
 
 /**
  * Reconstruct the continuous ATRAC1 spectrum.
@@ -40,7 +40,7 @@ export function dequantize() {
         blockModes[band] === 0 ? BFU_START_LONG[bfu] : BFU_START_SHORT[bfu]
 
       if (bitsPerSample > 0) {
-        const dequantized = dequantizeCoefficient(
+        const dequantized = spectrumQuantization.dequantize(
           quantizedCoefficients[bfu],
           scaleFactorIndices[bfu],
           bitsPerSample

package/codec/index.js

@@ -7,8 +7,8 @@ import { decode } from './pipeline/decoder.js'
 import { AeaFile } from './boundary/container.js'
 import { deserializeFrame, serializeFrame } from './syntax/frame.js'
 import { quantize, dequantize } from './quantization/spectrum.js'
-import { analyzeBands as qmfAnalysisStage } from './analysis/bands.js'
-import { transformSpectrum as mdctStage } from './analysis/spectrum.js'
+import { analyzeBands } from './analysis/bands.js'
+import { transformSpectrum } from './analysis/spectrum.js'
 import { pipe } from './utils.js'
 import { BufferPool } from './state.js'
 import { EncoderOptions } from './core/options.js'
@@ -26,8 +26,8 @@ export {
   pipe,
   encode,
   decode,
-  qmfAnalysisStage,
-  mdctStage,
+  analyzeBands as qmfAnalysisStage,
+  transformSpectrum as mdctStage,
   serializeFrame,
   deserializeFrame,
   quantize,

package/codec/quantization/stage.js

@@ -3,7 +3,7 @@
  */
 
 import { WORD_LENGTH_BITS } from '../core/tables.js'
-import { quantize as quantizeCoefficient } from './spectrum.js'
+import * as spectrumQuantization from './spectrum.js'
 
 /**
  * Materialize retained allocation as quantized ATRAC1 symbols.
@@ -30,7 +30,11 @@ export function quantize() {
       const data = bfuData[bfu].subarray(0, bfuSizes[bfu])
       const bitsPerSample = WORD_LENGTH_BITS[wordLengthIndices[bfu]]
       quantizedCoefficients.push(
-        quantizeCoefficient(data, scaleFactorIndices[bfu], bitsPerSample)
+        spectrumQuantization.quantize(
+          data,
+          scaleFactorIndices[bfu],
+          bitsPerSample
+        )
       )
     }
 

package/codec/signal/fft.js

@@ -1,66 +1,65 @@
-/**
- * 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.
- */
+/** Complex radix-2 Fast Fourier Transform. */
 
 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
+   * Transform split complex data in place.
+   *
+   * @param {Float32Array} real Real input and output components.
+   * @param {Float32Array} imaginary Imaginary input and output components.
    */
-  static fft(real, imag) {
+  static transform(real, imaginary) {
     const size = real.length
     if (size === 1) return
 
     const bits = Math.log2(size)
-
-    // Bit reversal
-    for (let i = 0; i < size; i++) {
+    for (let index = 0; index < size; index++) {
       let reversed = 0
-      let temp = i
-      for (let b = 0; b < bits; b++) {
-        reversed = (reversed << 1) | (temp & 1)
-        temp >>= 1
+      let remaining = index
+      for (let bit = 0; bit < bits; bit++) {
+        reversed = (reversed << 1) | (remaining & 1)
+        remaining >>= 1
       }
-      if (reversed > i) {
-        ;[real[i], real[reversed]] = [real[reversed], real[i]]
-        ;[imag[i], imag[reversed]] = [imag[reversed], imag[i]]
+      if (reversed > index) {
+        const realValue = real[index]
+        real[index] = real[reversed]
+        real[reversed] = realValue
+        const imaginaryValue = imaginary[index]
+        imaginary[index] = imaginary[reversed]
+        imaginary[reversed] = imaginaryValue
       }
     }
 
-    // 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)
+      const stepReal = Math.cos(angle)
+      const stepImaginary = Math.sin(angle)
 
       for (let start = 0; start < size; start += stride) {
         let twiddleReal = 1
-        let twiddleImag = 0
+        let twiddleImaginary = 0
 
-        for (let k = 0; k < halfStride; k++) {
-          const evenIndex = start + k
+        for (let offset = 0; offset < halfStride; offset++) {
+          const evenIndex = start + offset
           const oddIndex = evenIndex + halfStride
-
           const evenReal = real[evenIndex]
-          const evenImag = imag[evenIndex]
+          const evenImaginary = imaginary[evenIndex]
           const oddReal = real[oddIndex]
-          const oddImag = imag[oddIndex]
-
-          const tReal = oddReal * twiddleReal - oddImag * twiddleImag
-          const tImag = oddReal * twiddleImag + oddImag * twiddleReal
+          const oddImaginary = imaginary[oddIndex]
+          const rotatedReal =
+            oddReal * twiddleReal - oddImaginary * twiddleImaginary
+          const rotatedImaginary =
+            oddReal * twiddleImaginary + oddImaginary * twiddleReal
 
-          real[evenIndex] = evenReal + tReal
-          imag[evenIndex] = evenImag + tImag
-          real[oddIndex] = evenReal - tReal
-          imag[oddIndex] = evenImag - tImag
+          real[evenIndex] = evenReal + rotatedReal
+          imaginary[evenIndex] = evenImaginary + rotatedImaginary
+          real[oddIndex] = evenReal - rotatedReal
+          imaginary[oddIndex] = evenImaginary - rotatedImaginary
 
-          const nextReal = twiddleReal * wReal - twiddleImag * wImag
-          twiddleImag = twiddleReal * wImag + twiddleImag * wReal
+          const nextReal =
+            twiddleReal * stepReal - twiddleImaginary * stepImaginary
+          twiddleImaginary =
+            twiddleReal * stepImaginary + twiddleImaginary * stepReal
           twiddleReal = nextReal
         }
       }