carta1 1.1.10 → 1.3.0

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 { 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.
+ *
+ * @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 = [middleMdct, middleMdct, longMdct]
+
+  /**
+   * @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 = shortMdct.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),
+    }
+  }
+}

package/codec/boundary/pcm.js

@@ -0,0 +1,193 @@
+/**
+ * Carta1 PCM boundary conversions.
+ */
+
+import {
+  SAMPLE_RATE,
+  SAMPLES_PER_FRAME,
+  WAV_BITS_PER_SAMPLE,
+  WAV_BYTES_PER_SAMPLE,
+  WAV_DATA_OFFSET,
+  WAV_HEADER_SIZE,
+  WAV_PCM_MAX_NEGATIVE,
+  WAV_PCM_MAX_POSITIVE,
+} from '../core/constants.js'
+
+/**
+ * Write a four-character code.
+ *
+ * @param {DataView} output
+ * @param {number} offset
+ * @param {string} value
+ */
+function writeFourCc(output, offset, value) {
+  for (let i = 0; i < value.length; i++) {
+    output.setUint8(offset + i, value.charCodeAt(i))
+  }
+}
+
+/**
+ * Join complete PCM frames into one channel.
+ *
+ * @param {Float32Array[]} frames
+ * @returns {Float32Array}
+ */
+export function joinChannelFrames(frames) {
+  const sampleCount = frames.reduce((total, frame) => total + frame.length, 0)
+  const channel = new Float32Array(sampleCount)
+  let offset = 0
+
+  for (const frame of frames) {
+    channel.set(frame, offset)
+    offset += frame.length
+  }
+  return channel
+}
+
+/**
+ * Split planar PCM buffers into complete zero-padded codec frames.
+ *
+ * @param {Float32Array[]} buffers
+ * @param {number} [frameSize=SAMPLES_PER_FRAME]
+ * @returns {Generator<Float32Array>|Generator<[Float32Array, Float32Array]>}
+ * @throws {Error} If the channel count is unsupported
+ */
+export function* frameBufferToFrames(buffers, frameSize = SAMPLES_PER_FRAME) {
+  if (
+    !Array.isArray(buffers) ||
+    (buffers.length !== 1 && buffers.length !== 2) ||
+    !buffers.every(
+      (buffer) =>
+        buffer instanceof Float32Array && buffer.length === buffers[0].length
+    ) ||
+    !Number.isInteger(frameSize) ||
+    frameSize < 1
+  ) {
+    throw new RangeError(
+      'ATRAC1 framing requires one or two equally sized Float32 channels and a positive integer frame size'
+    )
+  }
+  if (buffers.length === 1) {
+    const [left] = buffers
+    for (let offset = 0; offset < left.length; offset += frameSize) {
+      const frame = new Float32Array(frameSize)
+      frame.set(left.subarray(offset, offset + frameSize))
+      yield frame
+    }
+    return
+  }
+
+  if (buffers.length === 2) {
+    const [left, right] = buffers
+    const sampleCount = left.length
+    for (let offset = 0; offset < sampleCount; offset += frameSize) {
+      const leftFrame = new Float32Array(frameSize)
+      const rightFrame = new Float32Array(frameSize)
+      leftFrame.set(left.subarray(offset, offset + frameSize))
+      rightFrame.set(right.subarray(offset, offset + frameSize))
+      yield [leftFrame, rightFrame]
+    }
+    return
+  }
+}
+
+/**
+ * Convert one normalized sample to signed PCM16.
+ *
+ * @param {number} sample
+ * @returns {number}
+ */
+export function floatToPcm16(sample) {
+  const clipped = Math.max(-1, Math.min(1, sample))
+  return clipped < 0
+    ? clipped * WAV_PCM_MAX_NEGATIVE
+    : clipped * WAV_PCM_MAX_POSITIVE
+}
+
+/**
+ * Create a PCM WAVE header.
+ *
+ * @param {Object} options
+ * @param {number} options.sampleCount
+ * @param {number} options.sampleRate
+ * @param {number} options.channels
+ * @returns {Uint8Array}
+ */
+export function createPcmWaveHeader({ sampleCount, sampleRate, channels }) {
+  const byteRate = sampleRate * channels * WAV_BYTES_PER_SAMPLE
+  const blockAlign = channels * WAV_BYTES_PER_SAMPLE
+  const dataSize = sampleCount * blockAlign
+  const output = new Uint8Array(WAV_HEADER_SIZE)
+  const view = new DataView(output.buffer)
+
+  writeFourCc(view, 0, 'RIFF')
+  view.setUint32(4, WAV_DATA_OFFSET + dataSize, true)
+  writeFourCc(view, 8, 'WAVE')
+  writeFourCc(view, 12, 'fmt ')
+  view.setUint32(16, 16, true)
+  view.setUint16(20, 1, true)
+  view.setUint16(22, channels, true)
+  view.setUint32(24, sampleRate, true)
+  view.setUint32(28, byteRate, true)
+  view.setUint16(32, blockAlign, true)
+  view.setUint16(34, WAV_BITS_PER_SAMPLE, true)
+  writeFourCc(view, 36, 'data')
+  view.setUint32(40, dataSize, true)
+  return output
+}
+
+/**
+ * Interleave planar normalized channels as PCM16.
+ *
+ * @param {Float32Array[]} channels
+ * @returns {Uint8Array}
+ */
+export function interleavePcm16(channels) {
+  if (
+    !Array.isArray(channels) ||
+    channels.length < 1 ||
+    !channels.every(
+      (channel) =>
+        channel instanceof Float32Array && channel.length === channels[0].length
+    )
+  ) {
+    throw new RangeError('PCM must contain equally sized Float32 channels')
+  }
+  const sampleCount = channels[0].length
+  const output = new Uint8Array(
+    sampleCount * channels.length * WAV_BYTES_PER_SAMPLE
+  )
+  const view = new DataView(output.buffer)
+  let offset = 0
+
+  for (let sample = 0; sample < sampleCount; sample++) {
+    for (const channel of channels) {
+      view.setInt16(offset, floatToPcm16(channel[sample]), true)
+      offset += WAV_BYTES_PER_SAMPLE
+    }
+  }
+  return output
+}
+
+/**
+ * Create a complete PCM WAVE byte image from planar channels.
+ *
+ * @param {Float32Array[]} channels
+ * @param {Object} [options]
+ * @param {number} [options.sampleRate=SAMPLE_RATE]
+ * @returns {Uint8Array}
+ */
+export function createPcmWave(channels, options = {}) {
+  const { sampleRate = SAMPLE_RATE } = options
+  const pcm = interleavePcm16(channels)
+  const sampleCount = channels[0].length
+  const header = createPcmWaveHeader({
+    sampleCount,
+    sampleRate,
+    channels: channels.length,
+  })
+  const output = new Uint8Array(header.length + pcm.length)
+  output.set(header)
+  output.set(pcm, header.length)
+  return output
+}

package/codec/boundary/processor.js

@@ -0,0 +1,208 @@
+/**
+ * Carta1 public processing facade.
+ */
+
+import {
+  AEA_HEADER_SIZE,
+  SAMPLE_RATE,
+  SAMPLES_PER_FRAME,
+  SOUND_UNIT_SIZE,
+  STREAM_FLUSH_TAIL_FRAMES,
+  STREAM_PRIMING_SAMPLES,
+} from '../core/constants.js'
+import { deserializeFrame, serializeFrame } from '../syntax/frame.js'
+import { AeaFile } from './container.js'
+import { createPcmWave, frameBufferToFrames, joinChannelFrames } from './pcm.js'
+import {
+  createAeaStreamingDecoder,
+  createAeaStreamingEncoder,
+  decodeAeaPcm,
+  encodeAeaPcm,
+} from './stream.js'
+
+/**
+ * High-level audio processing facade.
+ */
+export class AudioProcessor {
+  /**
+   * @param {Float32Array[]} channels
+   * @param {object} [options]
+   * @returns {Promise<Uint8Array>}
+   */
+  static encodeAeaPcm(channels, options = {}) {
+    return encodeAeaPcm(channels, options)
+  }
+
+  /**
+   * @param {Uint8Array|ArrayBuffer|Blob} input
+   * @returns {Promise<Float32Array[]>}
+   */
+  static decodeAeaPcm(input) {
+    return decodeAeaPcm(input)
+  }
+
+  /**
+   * @param {AsyncIterable<object>} audioFrames
+   * @param {object} [options]
+   * @returns {AsyncGenerator<object>}
+   */
+  static async *encodeStream(audioFrames, options = {}) {
+    const encoder = createAeaStreamingEncoder(options)
+    yield* encoder.frames(audioFrames)
+    yield* encoder.finish()
+  }
+
+  /**
+   * @param {AsyncIterable<object>} encodedFrames
+   * @param {object} [options]
+   * @returns {AsyncGenerator<object>}
+   */
+  static async *decodeStream(encodedFrames, options = {}) {
+    const decoder = createAeaStreamingDecoder(options)
+    yield* decoder.frames(encodedFrames)
+    yield* decoder.finish()
+  }
+
+  /**
+   * @param {Float32Array[]} buffers
+   * @param {number} [frameSize]
+   * @returns {Generator<Float32Array>|Generator<[Float32Array, Float32Array]>}
+   */
+  static *frameBufferToFrames(buffers, frameSize) {
+    yield* frameBufferToFrames(buffers, frameSize)
+  }
+
+  /**
+   * @param {AsyncIterable|Iterable} frameStream
+   * @returns {Promise<Array>}
+   */
+  static async collectFrames(frameStream) {
+    const frames = []
+    for await (const frame of frameStream) {
+      frames.push(frame)
+    }
+    return frames
+  }
+
+  /**
+   * @param {AsyncIterable<object>} encodedFrames
+   * @param {object} [options]
+   * @returns {Promise<Blob>}
+   */
+  static async createAeaBlob(encodedFrames, options = {}) {
+    const { title = 'encoded by atrac1.js', channelCount = 1 } = options
+    const frames = []
+    for await (const frame of encodedFrames) {
+      frames.push(serializeFrame(frame))
+    }
+
+    const timelineFrames = frames.length / channelCount
+    const sampleCount =
+      options.sampleCount ??
+      Math.max(0, timelineFrames - STREAM_FLUSH_TAIL_FRAMES) * SAMPLES_PER_FRAME
+    const header = AeaFile.createHeader(
+      title,
+      frames.length,
+      channelCount,
+      sampleCount,
+      STREAM_PRIMING_SAMPLES
+    )
+    return new Blob([header, ...frames], { type: 'application/octet-stream' })
+  }
+
+  /**
+   * @param {Blob} blob
+   * @returns {Promise<object>} Parsed AEA data.
+   */
+  static async parseAeaBlob(blob) {
+    const buffer = await blob.arrayBuffer()
+    const header = new Uint8Array(buffer.slice(0, AEA_HEADER_SIZE))
+    const info = AeaFile.parseHeader(header)
+    const frameData = []
+
+    for (let offset = AEA_HEADER_SIZE; offset < buffer.byteLength;) {
+      const frame = new Uint8Array(
+        buffer.slice(offset, offset + SOUND_UNIT_SIZE)
+      )
+      if (frame.length === SOUND_UNIT_SIZE) {
+        frameData.push(frame)
+      }
+      offset += SOUND_UNIT_SIZE
+    }
+    return { info, frameData }
+  }
+
+  /**
+   * @param {Uint8Array[]} frameData
+   * @returns {Generator<object>}
+   */
+  static *deserializedFrameStream(frameData) {
+    for (const frame of frameData) {
+      yield deserializeFrame(frame)
+    }
+  }
+
+  /**
+   * @param {Float32Array[]|[Float32Array, Float32Array][]} pcmFrames
+   * @param {number} [channelCount=1]
+   * @param {number} [sampleRate=SAMPLE_RATE]
+   * @returns {Blob}
+   */
+  static createPcmWaveBlob(
+    pcmFrames,
+    channelCount = 1,
+    sampleRate = SAMPLE_RATE
+  ) {
+    let channels
+    if (channelCount === 1) {
+      channels = [joinChannelFrames(pcmFrames)]
+    } else if (channelCount === 2) {
+      channels = [
+        joinChannelFrames(pcmFrames.map(([left]) => left)),
+        joinChannelFrames(pcmFrames.map(([, right]) => right)),
+      ]
+    } else {
+      throw new Error(`Unsupported channel count: ${channelCount}`)
+    }
+    return new Blob([createPcmWave(channels, { sampleRate })], {
+      type: 'audio/wav',
+    })
+  }
+
+  /**
+   * Preserve the supported WAVE facade name.
+   *
+   * @param {Float32Array[]|[Float32Array, Float32Array][]} pcmFrames
+   * @param {number} [channelCount=1]
+   * @param {number} [sampleRate=SAMPLE_RATE]
+   * @returns {Blob}
+   */
+  static createWavBlob(pcmFrames, channelCount = 1, sampleRate = SAMPLE_RATE) {
+    return AudioProcessor.createPcmWaveBlob(pcmFrames, channelCount, sampleRate)
+  }
+
+  /**
+   * Assemble PCM frames using the supported interleaved result shape.
+   *
+   * @param {Float32Array[]|[Float32Array, Float32Array][]} pcmFrames
+   * @param {number} channelCount
+   * @returns {Float32Array}
+   */
+  static assemblePcmFrames(pcmFrames, channelCount) {
+    if (channelCount === 1) {
+      return joinChannelFrames(pcmFrames)
+    }
+    if (channelCount !== 2) {
+      throw new Error(`Unsupported channel count: ${channelCount}`)
+    }
+
+    const left = joinChannelFrames(pcmFrames.map(([channel]) => channel))
+    const right = joinChannelFrames(pcmFrames.map(([, channel]) => channel))
+    const pcm = new Float32Array(Math.max(left.length, right.length) * 2)
+    for (let i = 0; i < pcm.length / 2; i++) {
+      pcm[i * 2] = left[i] ?? 0
+      pcm[i * 2 + 1] = right[i] ?? 0
+    }
+    return pcm
+  }
+}

package/codec/{io/readers.js → boundary/reader.js}

@@ -6,7 +6,8 @@
  */
 
 import fs from 'fs'
-import { AeaFile, deserializeFrame } from './serialization.js'
+import { AeaFile } from './container.js'
+import { deserializeFrame } from '../syntax/frame.js'
 import { AEA_HEADER_SIZE, SOUND_UNIT_SIZE } from '../core/constants.js'
 
 /**