carta1 1.1.9 → 1.2.0

package/README.md

@@ -1,128 +1,202 @@
 # Carta1
 
-An ATRAC1 audio codec implementation in JS.
+Carta1 is an ATRAC1 encoder and decoder in JavaScript. It converts PCM WAVE
+audio to Sony's AEA container, decodes AEA back to PCM WAVE, exposes stateful
+frame and stream APIs, and ships browser Web Worker bundles.
 
-## Features
+## Supported format
 
-- Pure JavaScript implementation of ATRAC1 codec
-- Encoding WAV to AEA (ATRAC1) format
-- Decoding AEA to WAV format
-- Command-line interface
-- Browser-compatible with Web Workers
-- Streaming support for large files
+| Property           | Support                                       |
+| ------------------ | --------------------------------------------- |
+| Sample rate        | 44.1 kHz                                      |
+| Channels           | Mono or stereo                                |
+| Frame size         | 512 PCM samples per channel                   |
+| Encoded sound unit | 212 bytes per channel                         |
+| Nominal bitrate    | About 146 kbps per channel / 292 kbps stereo  |
+| Container          | AEA                                           |
+| JavaScript PCM     | Planar `Float32Array`, normalized `-1` to `1` |
+
+Stereo channels are encoded independently and stored as interleaved AEA sound
+units.
 
 ## Installation
 
+Carta1 is an ES module and requires Node.js 20.16 or newer.
+
 ```bash
 npm install carta1
 ```
 
-## CLI Usage
-
-### Encoding
+To work from a repository checkout:
 
 ```bash
-carta1 --encode input.wav output.aea
+npm ci
+npm run check
 ```
 
-### Decoding
+## CLI
+
+Run the installed executable directly, or use `npx carta1` from a project that
+depends on Carta1:
 
 ```bash
+carta1 --encode input.wav output.aea
 carta1 --decode input.aea output.wav
-```
-
-### Options
-
-- `-e, --encode` - Encode WAV to AEA
-- `-d, --decode` - Decode AEA to WAV
-- `-j, --json` - Dump AEA file structure to JSON
-- `-q, --quiet` - Suppress all output except errors
-- `-f, --force` - Overwrite output file if it exists
-- `-t, --title <title>` - Custom title for AEA file metadata (encoding only)
+carta1 --json input.aea structure.json
 
-## Browser Usage
-
-```html
-<script src="https://unpkg.com/carta1/dist/carta1-worker.min.js"></script>
-<script src="https://unpkg.com/carta1/dist/carta1-worker-interface.min.js"></script>
+npx carta1 --encode input.wav output.aea
 ```
 
-```javascript
-// Create codec instance
-const codec = new Carta1Worker('carta1-worker.min.js')
+The encoder accepts mono or stereo PCM WAVE input. Carta1 is designed for
+44.1 kHz audio; it warns when the input sample rate differs. Decoding writes
+signed 16-bit PCM WAVE output.
+
+| Option                | Meaning                                              |
+| --------------------- | ---------------------------------------------------- |
+| `-e, --encode`        | Encode PCM WAVE to AEA.                              |
+| `-d, --decode`        | Decode AEA to PCM WAVE.                              |
+| `-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.                    |
+| `-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.                            |
+| `-h, --help`          | Print command help.                                  |
+
+Exactly one of `--encode`, `--decode`, and `--json` is required. The input and
+output are positional paths. Existing output is preserved unless `--force` is
+provided.
+
+## JavaScript API
+
+### Complete AEA files
+
+Use `encodeAeaPcm()` and `decodeAeaPcm()` when the complete input fits in
+memory:
+
+```js
+import { decodeAeaPcm, encodeAeaPcm } from 'carta1'
+
+const aea = await encodeAeaPcm([left, right], {
+  allocationBias: 1.0,
+  title: 'Example',
+})
+const [decodedLeft, decodedRight] = await decodeAeaPcm(aea)
+```
 
-// Encode PCM to ATRAC1
-const result = await codec.encode(pcmData, options)
+`encodeAeaPcm()` returns a `Uint8Array` containing a complete AEA file.
+`decodeAeaPcm()` accepts AEA bytes or a `Blob` and returns normalized planar
+`Float32Array` channels. A mono input uses `[mono]`. The final partial input
+frame is zero-padded.
 
-// Decode ATRAC1 to PCM
-const wavData = await codec.decode(aeaData)
+### Stateful frames
 
-// Clean up
-codec.terminate()
-```
+`encode()` and `decode()` create closures for chronological, complete mono
+frames. Reuse each closure for one stream:
 
-## API Reference
+```js
+import { decode, encode, EncoderOptions } from 'carta1'
 
-### Node.js
+const encodeFrame = encode(new EncoderOptions({ transientThresholdLow: 1.0 }))
+const decodeFrame = decode()
 
-```javascript
-import { encode, decode, AudioProcessor } from 'carta1'
+const encoded = encodeFrame(new Float32Array(512))
+const decoded = decodeFrame(encoded)
+```
 
-// Encode PCM frames
-const encoder = encode(options)
-const encodedFrame = encoder(pcmFrame)
+Use separate closures for separate streams and for the left and right channels
+of stereo audio. `AudioProcessor.encodeStream()` and `decodeStream()` handle
+that ownership automatically.
 
-// Decode ATRAC1 frames
-const decoder = decode()
-const pcmFrame = decoder(encodedFrame)
-```
+### Encoder options
 
-### Browser Worker API
+`EncoderOptions` validates these settings:
 
-#### `new Carta1Worker(workerPath)`
+- `transientThresholdLow`, `transientThresholdMid`, and
+  `transientThresholdHigh` tune short-block detection per frequency band.
+- `allocationBias` changes how strongly allocation favors louder spectral
+  components.
+- `fixedBlockModes` accepts `[low, mid, high]`, where low and mid are `0` or
+  `2`, and high is `0` or `3`; this bypasses transient detection.
 
-Create a new codec worker instance.
+## Browser worker
 
-#### `encode(pcmData, options)`
+The production build writes a worker and an ES module client to `dist/`. Serve
+both from a location allowed by your application's worker and Content Security
+Policy settings:
 
-Encode PCM audio data to ATRAC1 format.
+```js
+import { Carta1Worker } from '/vendor/carta1-worker-interface.min.js'
 
-#### `decode(aeaData)`
+const codec = new Carta1Worker('/vendor/carta1-worker.min.js')
 
-Decode ATRAC1 data to PCM format.
+const { aeaBlob } = await codec.encode([left, right], {
+  allocationBias: 1.0,
+})
+const parsed = await codec.parseAeaBlob(aeaBlob)
+const { wavBlob, info } = await codec.decode({
+  aeaData: parsed.frameData,
+  info: parsed.info,
+})
+const optionMetadata = await codec.getEncoderOptions()
 
-#### `parseAeaBlob(blob)`
+codec.terminate()
+```
 
-Parse AEA file blob to extract metadata.
+Always call `terminate()` when the worker is no longer needed. The build also
+produces `dist/carta1.min.js`, a UMD bundle exposing the main JavaScript API as
+the global `Carta1` object.
 
-#### `terminate()`
+## Compatibility and limitations
 
-Clean up worker resources.
+- Encoding is fixed to the 44.1 kHz ATRAC1 profile described above; Carta1 does
+  not resample input.
+- JavaScript APIs use normalized planar PCM. Web Audio channel data already
+  follows this convention.
+- Stateful frame APIs must receive frames in order and must not be shared by
+  independent streams.
+- AEA stores whole frames rather than an exact source sample count, so a final
+  partial frame is represented with zero padding.
+- Browser worker assets must be served from a location permitted by the page's
+  worker and Content Security Policy rules.
 
 ## Development
 
-```bash
-# Install dependencies
-npm install
-
-# Run tests
-npm test
+Implementation concerns are split without hiding the top-level pipeline:
 
-# Build minified versions
-npm run build
+| Path                | Responsibility                                      |
+| ------------------- | --------------------------------------------------- |
+| `codec/pipeline/`   | Ordered encoder and decoder stage composition.      |
+| `codec/analysis/`   | Transient analysis and encoder decisions.           |
+| `codec/coding/`     | Bit allocation and quantization.                    |
+| `codec/transforms/` | FFT, QMF, MDCT, and inverse transforms.             |
+| `codec/io/`         | Bitstreams, AEA serialization, and stream adapters. |
+| `codec/core/`       | Constants, options, and reusable buffer ownership.  |
+| `codec/browser/`    | Web Worker implementation and client.               |
+| `bin/`              | Command-line boundary.                              |
+| `tests/`            | Unit, serialization, and pipeline tests.            |
 
-# Lint code
-npm run lint
+Common commands are:
 
-# Format code
-npm run format
+```bash
+npm test            # Run the test suite once
+npm run test:watch  # Re-run tests while editing
+npm run lint        # Check JavaScript and formatting
+npm run format      # Apply repository formatting
+npm run build       # Build the three browser bundles
+npm run check       # Run lint, tests, and the production build
 ```
 
-## Acknowledgements
+Run `npm run check` before submitting a change. Pull requests and pushes run
+the same gate in CI.
 
-This project would not have been possible without:
+## Acknowledgements
 
-- [**AtracDEnc**](https://github.com/dcherednik/atracdenc) by [Daniel Cherednik](https://github.com/dcherednik) - The reference ATRAC implementation that provided invaluable insights into the codec's inner workings and served as the primary source for understanding the ATRAC1 format specification.
+This project would not have been possible without
+[AtracDEnc](https://github.com/dcherednik/atracdenc) by
+[Daniel Cherednik](https://github.com/dcherednik), the reference ATRAC
+implementation used to understand the ATRAC1 format and codec behavior.
 
 ## License
 

package/bin/cli.js

@@ -19,9 +19,10 @@ import { performance } from 'perf_hooks'
 import cliProgress from 'cli-progress'
 import wav from 'wav'
 
-import { AudioProcessor } from '../codec/io/processor.js'
-import { AeaReader } from '../codec/io/readers.js'
-import { deserializeFrame, AeaFile } from '../codec/io/serialization.js'
+import { AudioProcessor } from '../codec/boundary/processor.js'
+import { AeaReader } from '../codec/boundary/reader.js'
+import { AeaFile } from '../codec/boundary/container.js'
+import { deserializeFrame } from '../codec/syntax/frame.js'
 import { EncoderOptions } from '../codec/core/options.js'
 import {
   SAMPLE_RATE,
@@ -483,6 +484,7 @@ async function encodeFile(inputFile, outputFile, options) {
     const blob = await AudioProcessor.createAeaBlob(encodedFrames, {
       title,
       channelCount: reader.channels,
+      sampleCount: reader.totalSamples,
     })
 
     const buffer = await blob.arrayBuffer()
@@ -533,11 +535,13 @@ async function decodeFile(inputFile, outputFile, options) {
 
     const decodedFrames = AudioProcessor.decodeStream(reader, {
       channelCount: metadata.channelCount,
+      primingSampleCount: metadata.primingSampleCount,
+      sampleCount: metadata.sampleCount,
       onProgress,
     })
 
     const pcmFrames = await AudioProcessor.collectFrames(decodedFrames)
-    const wavBlob = AudioProcessor.createWavBlob(
+    const wavBlob = AudioProcessor.createPcmWaveBlob(
       pcmFrames,
       metadata.channelCount,
       SAMPLE_RATE

package/codec/{coding/bitallocation.js → allocation/solve.js}

@@ -27,13 +27,15 @@ import {
   FRAME_OVERHEAD_BITS,
   BITS_PER_BFU_METADATA,
   MAX_WORD_LENGTH_INDEX,
+} from '../core/constants.js'
+import {
   WORD_LENGTH_BITS,
   INV_POWER_OF_TWO,
   SCALE_FACTORS,
   BFU_AMOUNTS,
   WORD_LENGTH_DELTA_BITS,
   DISTORTION_DELTA_FACTORS,
-} from '../core/constants.js'
+} from '../core/tables.js'
 
 const biasedScaleFactorCache = new Map()
 
@@ -61,84 +63,43 @@ function buildBiasedScaleFactorTable(bias) {
 }
 
 /**
- * Allocate bits by finding the optimal BFU count and distribution using RDO.
- * This function searches through the valid BFU counts to find the one that
- * minimizes the total perceptual distortion.
+ * Evaluate one legal active-BFU count.
  *
- * @param {Array<Float32Array>} bfuData
- * @param {Int32Array} bfuSizes
+ * @param {number} activeBfuCount
  * @param {number} maxBfuCount
- * @param {number} allocationBias
- * @returns {{bfuCount:number, allocation:Int32Array, scaleFactorIndices:Int32Array}}
+ * @param {Int32Array} bfuSizes
+ * @param {number} remainingBits
+ * @param {Float64Array} biasedScaleFactors
+ * @param {Int32Array} allScaleFactorIndices
+ * @param {Float32Array} zeroBitDistortions
+ * @returns {object} Allocation result.
  */
-export function allocateBits(bfuData, bfuSizes, maxBfuCount, allocationBias) {
-  const allScaleFactorIndices = new Int32Array(maxBfuCount)
-  const zeroBitDistortions = new Float32Array(maxBfuCount)
-  const biasedScaleFactors = buildBiasedScaleFactorTable(allocationBias)
-
-  for (let i = 0; i < maxBfuCount; i++) {
-    const sz = bfuSizes[i] | 0
-    if (sz === 0) continue
-
-    const sfi = findScaleFactor(bfuData[i], sz)
-    allScaleFactorIndices[i] = sfi
-    if (sfi > 0) {
-      const effectiveScaleFactor = biasedScaleFactors[sfi]
-      zeroBitDistortions[i] = effectiveScaleFactor * 2.0 * sz
-    }
-  }
-
-  let bestResult = null
-  let minTotalDistortion = Infinity
-
-  for (const candidateBfuCount of BFU_AMOUNTS) {
-    if (candidateBfuCount > maxBfuCount) continue
-
-    const availableBits =
-      FRAME_BITS -
-      FRAME_OVERHEAD_BITS -
-      candidateBfuCount * BITS_PER_BFU_METADATA
-
-    if (availableBits < 0) continue
-
-    const rdoResult = distributeBitsRDO(
-      candidateBfuCount,
-      bfuSizes,
-      availableBits,
-      biasedScaleFactors,
-      allScaleFactorIndices
-    )
-
-    const totalDistortion = calculateTotalDistortion(
-      candidateBfuCount,
-      maxBfuCount,
-      bfuSizes,
-      rdoResult.wordLengths,
-      rdoResult.scaleFactorIndices,
-      biasedScaleFactors,
-      zeroBitDistortions
-    )
-
-    if (totalDistortion < minTotalDistortion) {
-      minTotalDistortion = totalDistortion
-      bestResult = {
-        bfuCount: candidateBfuCount,
-        allocation: rdoResult.wordLengths,
-        scaleFactorIndices: rdoResult.scaleFactorIndices,
-      }
-    }
-  }
-
-  if (!bestResult) {
-    const fallbackBfuCount = BFU_AMOUNTS[0]
-    return {
-      bfuCount: fallbackBfuCount,
-      allocation: new Int32Array(fallbackBfuCount),
-      scaleFactorIndices: new Int32Array(NUM_BFUS),
-    }
-  }
-
-  return bestResult
+function search(
+  activeBfuCount,
+  maxBfuCount,
+  bfuSizes,
+  remainingBits,
+  biasedScaleFactors,
+  allScaleFactorIndices,
+  zeroBitDistortions
+) {
+  const allocation = distributeBits(
+    activeBfuCount,
+    bfuSizes,
+    remainingBits,
+    biasedScaleFactors,
+    allScaleFactorIndices
+  )
+  const distortion = measureDistortion(
+    activeBfuCount,
+    maxBfuCount,
+    bfuSizes,
+    allocation.wordLengths,
+    allocation.scaleFactorIndices,
+    biasedScaleFactors,
+    zeroBitDistortions
+  )
+  return { distortion, ...allocation }
 }
 
 /**
@@ -154,7 +115,7 @@ export function allocateBits(bfuData, bfuSizes, maxBfuCount, allocationBias) {
  * @param {Float32Array} zeroBitDistortions
  * @returns {number}
  */
-function calculateTotalDistortion(
+function measureDistortion(
   activeBfuCount,
   maxBfuCount,
   bfuSizes,
@@ -198,9 +159,9 @@ function calculateTotalDistortion(
  * @param {number} remainingBits
  * @param {Float64Array} biasedScaleFactors
  * @param {Int32Array} allScaleFactorIndices
- * @returns {{wordLengths: Int32Array, scaleFactorIndices: Int32Array}}
+ * @returns {object} Retained allocation decisions.
  */
-function distributeBitsRDO(
+function distributeBits(
   activeBfuCount,
   bfuSizes,
   remainingBits,
@@ -280,24 +241,6 @@ function distributeBitsRDO(
   return { wordLengths, scaleFactorIndices: allScaleFactorIndices }
 }
 
-/**
- * Find the optimal scale factor index for a set of coefficients.
- * Same semantics as the original.
- * @param {Float32Array} coefficients
- * @param {number} length
- * @returns {number}
- */
-export function findScaleFactor(coefficients, length) {
-  let maxAmplitude = 0.0
-  for (let i = 0; i < length; i++) {
-    const a = Math.abs(coefficients[i])
-    if (a > maxAmplitude) maxAmplitude = a
-  }
-  if (maxAmplitude === 0) return 0
-  const index = Math.ceil(3 * (Math.log2(maxAmplitude) + 21))
-  return Math.max(0, Math.min(63, index))
-}
-
 /**
  * Restores max-heap property by sifting an element down from a given position.
  *
@@ -339,3 +282,94 @@ function siftDown(heapIndices, heapPriorities, startIndex, heapSize) {
   heapIndices[i] = idxVal
   heapPriorities[i] = prVal
 }
+
+/**
+ * Allocate bits by finding the optimal BFU count and distribution using RDO.
+ * This function searches through the valid BFU counts to find the one that
+ * minimizes the total perceptual distortion.
+ *
+ * @param {Array<Float32Array>} bfuData
+ * @param {Int32Array} bfuSizes
+ * @param {number} maxBfuCount
+ * @param {number} allocationBias
+ * @returns {{bfuCount:number, allocation:Int32Array, scaleFactorIndices:Int32Array}}
+ */
+export function solve(bfuData, bfuSizes, maxBfuCount, allocationBias) {
+  const allScaleFactorIndices = new Int32Array(maxBfuCount)
+  const zeroBitDistortions = new Float32Array(maxBfuCount)
+  const biasedScaleFactors = buildBiasedScaleFactorTable(allocationBias)
+
+  for (let i = 0; i < maxBfuCount; i++) {
+    const sz = bfuSizes[i] | 0
+    if (sz === 0) continue
+
+    const sfi = findScaleFactor(bfuData[i], sz)
+    allScaleFactorIndices[i] = sfi
+    if (sfi > 0) {
+      const effectiveScaleFactor = biasedScaleFactors[sfi]
+      zeroBitDistortions[i] = effectiveScaleFactor * 2.0 * sz
+    }
+  }
+
+  let bestResult = null
+  let minTotalDistortion = Infinity
+
+  for (const candidateBfuCount of BFU_AMOUNTS) {
+    if (candidateBfuCount > maxBfuCount) continue
+
+    const availableBits =
+      FRAME_BITS -
+      FRAME_OVERHEAD_BITS -
+      candidateBfuCount * BITS_PER_BFU_METADATA
+
+    if (availableBits < 0) continue
+
+    const result = search(
+      candidateBfuCount,
+      maxBfuCount,
+      bfuSizes,
+      availableBits,
+      biasedScaleFactors,
+      allScaleFactorIndices,
+      zeroBitDistortions
+    )
+
+    if (result.distortion < minTotalDistortion) {
+      minTotalDistortion = result.distortion
+      bestResult = {
+        bfuCount: candidateBfuCount,
+        allocation: result.wordLengths,
+        scaleFactorIndices: result.scaleFactorIndices,
+      }
+    }
+  }
+
+  if (!bestResult) {
+    const fallbackBfuCount = BFU_AMOUNTS[0]
+    return {
+      bfuCount: fallbackBfuCount,
+      allocation: new Int32Array(fallbackBfuCount),
+      scaleFactorIndices: new Int32Array(NUM_BFUS),
+    }
+  }
+
+  return bestResult
+}
+
+/**
+ * Find the optimal scale factor index for a set of coefficients.
+ * Same semantics as the original.
+ * @param {Float32Array} coefficients
+ * @param {number} length
+ * @returns {number}
+ */
+export function findScaleFactor(coefficients, length) {
+  let maxAmplitude = 0.0
+  for (let i = 0; i < length; i++) {
+    const a = Math.abs(coefficients[i])
+    if (a > maxAmplitude) maxAmplitude = a
+  }
+  if (maxAmplitude === 0) return 0
+  const index = Math.ceil(3 * (Math.log2(maxAmplitude) + 21))
+  return Math.max(0, Math.min(63, index))
+}

package/codec/allocation/source.js

@@ -0,0 +1,69 @@
+/**
+ * Carta1 allocation-source preparation.
+ */
+
+import {
+  BFU_BAND_BOUNDARIES,
+  BFU_START_LONG,
+  BFU_START_SHORT,
+  SPECS_PER_BFU,
+} from '../core/tables.js'
+
+/**
+ * Group spectral coefficients into block floating units.
+ *
+ * @param {Float32Array} coefficients
+ * @param {Array<number>} blockModes
+ * @returns {object} Grouped bit-frequency units.
+ */
+export function groupIntoBFUs(coefficients, blockModes) {
+  const bfuData = []
+  const bfuSizes = []
+  let coeffIndex = 0
+  let bfuIndex = 0
+
+  for (let band = 0; band < 3; band++) {
+    const bandStart = coeffIndex
+    const bandSize = band === 2 ? 256 : 128
+    const bandEnd = band < 2 ? BFU_BAND_BOUNDARIES[band] : SPECS_PER_BFU.length
+    const startPositions =
+      blockModes[band] === 0 ? BFU_START_LONG : BFU_START_SHORT
+
+    while (bfuIndex < bandEnd) {
+      const size = SPECS_PER_BFU[bfuIndex]
+      const startPos = startPositions[bfuIndex] - bandStart
+      const endPos = startPos + size
+      const bfu = new Float32Array(size)
+
+      if (startPos >= 0 && endPos <= bandSize) {
+        bfu.set(coefficients.subarray(bandStart + startPos, bandStart + endPos))
+      } else if (startPos < bandSize && endPos > 0) {
+        const srcStart = Math.max(0, startPos)
+        const srcEnd = Math.min(bandSize, endPos)
+        bfu.set(
+          coefficients.subarray(bandStart + srcStart, bandStart + srcEnd),
+          Math.max(0, -startPos)
+        )
+      }
+
+      bfuData.push(bfu)
+      bfuSizes.push(size)
+      bfuIndex++
+    }
+
+    coeffIndex += bandSize
+  }
+
+  return { bfuData, bfuSizes, bfuCount: bfuIndex }
+}
+
+/**
+ * Prepare the spectrum as an allocation source.
+ *
+ * @param {Float32Array} coefficients
+ * @param {Array<number>} blockModes
+ * @returns {object} Allocation source.
+ */
+export function prepare(coefficients, blockModes) {
+  return groupIntoBFUs(coefficients, blockModes)
+}