carta1 1.0.0

package/codec/analysis/transient.js

@@ -0,0 +1,226 @@
+/**
+ * Carta1 Audio Codec - Transient Detection Module
+ *
+ * Detects transients using spectral flux analysis to prevent pre-echo artifacts.
+ * Combines multiple spectral features to identify sudden changes in signal
+ * 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
+}
+
+/**
+ * Calculate all spectral features for transient detection
+ * @param {Float32Array} currentCoeffs - Current frame coefficients
+ * @param {Float32Array} prevCoeffs - Previous frame coefficients
+ * @returns {Object} Computed spectral features
+ */
+function calculateSpectralFeatures(currentCoeffs, prevCoeffs) {
+  // Calculate spectral flux (positive differences only)
+  const spectralFlux = calculateSpectralFlux(currentCoeffs, prevCoeffs)
+
+  // Calculate spectral flatness for both frames
+  const currentFlatness = calculateSpectralFlatness(currentCoeffs)
+  const prevFlatness = calculateSpectralFlatness(prevCoeffs)
+  const flatnessChange = Math.abs(currentFlatness - prevFlatness)
+
+  // Calculate high-frequency content ratio
+  const currentHfRatio = calculateHighFrequencyRatio(currentCoeffs)
+  const prevHfRatio = calculateHighFrequencyRatio(prevCoeffs)
+  const hfChange = Math.abs(currentHfRatio - prevHfRatio)
+
+  // Calculate energy change in dB
+  const energyChange = calculateEnergyChange(currentCoeffs, prevCoeffs)
+
+  return {
+    spectralFlux,
+    flatnessChange,
+    hfChange,
+    energyChange,
+  }
+}
+
+/**
+ * Calculate normalized spectral flux (positive spectral differences)
+ * High values indicate sudden onset of new spectral components
+ */
+function calculateSpectralFlux(currentCoeffs, prevCoeffs) {
+  let flux = 0
+  let currentEnergy = 0
+
+  for (let i = 0; i < currentCoeffs.length; i++) {
+    const currentMag = Math.abs(currentCoeffs[i])
+    const prevMag = Math.abs(prevCoeffs[i])
+
+    // Only count positive differences (new energy)
+    const diff = currentMag - prevMag
+    if (diff > 0) {
+      flux += diff
+    }
+
+    currentEnergy += currentMag * currentMag
+  }
+
+  // Normalize by current frame energy to make threshold independent of level
+  const normalization = Math.sqrt(currentEnergy) || 1e-6
+  return flux / normalization
+}
+
+/**
+ * Calculate spectral flatness (geometric mean / arithmetic mean)
+ * Measures how noise-like vs tonal the spectrum is
+ * @param {Float32Array} coeffs - Spectral coefficients
+ * @returns {number} Flatness measure (0 = tonal, 1 = noise-like)
+ */
+function calculateSpectralFlatness(coeffs) {
+  const EPSILON = 1e-10
+  let sumLog = 0
+  let sumLinear = 0
+  let validBins = 0
+
+  for (let i = 0; i < coeffs.length; i++) {
+    const magnitude = Math.abs(coeffs[i])
+    if (magnitude > EPSILON) {
+      sumLog += Math.log(magnitude)
+      sumLinear += magnitude
+      validBins++
+    }
+  }
+
+  if (validBins === 0) return 0
+
+  const geometricMean = Math.exp(sumLog / validBins)
+  const arithmeticMean = sumLinear / validBins
+
+  return arithmeticMean > EPSILON ? geometricMean / arithmeticMean : 0
+}
+
+/**
+ * Calculate ratio of high-frequency to total energy
+ * High values indicate bright/harsh sounds that are perceptually important
+ * @param {Float32Array} coeffs - Spectral coefficients
+ * @returns {number} High-frequency energy ratio (0-1)
+ */
+function calculateHighFrequencyRatio(coeffs) {
+  const midPoint = Math.floor(coeffs.length / 2)
+  let lowEnergy = 0
+  let highEnergy = 0
+
+  for (let i = 0; i < midPoint; i++) {
+    lowEnergy += coeffs[i] * coeffs[i]
+  }
+
+  for (let i = midPoint; i < coeffs.length; i++) {
+    highEnergy += coeffs[i] * coeffs[i]
+  }
+
+  const totalEnergy = lowEnergy + highEnergy
+  return totalEnergy > 0 ? highEnergy / totalEnergy : 0
+}
+
+/**
+ * Calculate energy change between frames in dB
+ * @param {Float32Array} currentCoeffs - Current frame coefficients
+ * @param {Float32Array} prevCoeffs - Previous frame coefficients
+ * @returns {number} Energy change in dB (positive values only)
+ */
+function calculateEnergyChange(currentCoeffs, prevCoeffs) {
+  let currentEnergy = 0
+  let prevEnergy = 0
+
+  for (let i = 0; i < currentCoeffs.length; i++) {
+    currentEnergy += currentCoeffs[i] * currentCoeffs[i]
+    prevEnergy += prevCoeffs[i] * prevCoeffs[i]
+  }
+
+  // Avoid log of zero and ensure minimum energy
+  currentEnergy = Math.max(currentEnergy, 1e-10)
+  prevEnergy = Math.max(prevEnergy, 1e-10)
+
+  const changeDb = 10 * Math.log10(currentEnergy / prevEnergy)
+
+  // Only interested in energy increases (potential transients)
+  return Math.max(0, changeDb)
+}
+
+/**
+ * Calculate unified transient score from spectral features
+ * Uses perceptually-motivated combination instead of magic numbers
+ * @param {Object} features - Spectral features
+ * @returns {number} Transient score
+ */
+function calculateTransientScore(features) {
+  const { spectralFlux, flatnessChange, hfChange, energyChange } = features
+
+  // Spectral flux is the primary indicator - it directly measures
+  // sudden onset of new frequency components
+  const fluxContribution = spectralFlux
+
+  // Flatness change indicates transition between tonal and noise-like
+  // signals (e.g., pitched to unpitched percussion)
+  // Scale by sqrt to reduce dominance
+  const flatnessContribution = Math.sqrt(flatnessChange)
+
+  // High-frequency changes are perceptually important but shouldn't
+  // dominate the decision. Use log scaling for perceptual relevance
+  const hfContribution = Math.log1p(hfChange * 10) / Math.log1p(10)
+
+  // Energy changes in dB are already perceptually scaled
+  // Normalize to 0-1 range assuming 30dB is a strong transient
+  const energyContribution = Math.min(energyChange / 30, 1)
+
+  // Combine features with equal perceptual importance
+  // Each contribution is normalized to roughly 0-1 range
+  return (
+    (fluxContribution +
+      flatnessContribution +
+      hfContribution +
+      energyContribution) /
+    4
+  )
+}

package/codec/browser/interface.js

@@ -0,0 +1,188 @@
+/**
+ * Carta1 Worker Interface - Client-side API
+ *
+ * Provides a clean async interface for encoding and decoding ATRAC1 audio
+ * using Web Workers for non-blocking operation.
+ *
+ * Usage:
+ *   const codec = new Carta1Worker('carta1-worker.min.js')
+ *   const result = await codec.encode(pcmData, options)
+ *   codec.terminate()
+ *
+ * The worker path can be customized to match your deployment:
+ *   new Carta1Worker('/js/carta1-worker.min.js')
+ *   new Carta1Worker('https://cdn.example.com/carta1-worker.min.js')
+ */
+
+class Carta1Worker {
+  /**
+   * Create a new ATRAC1 codec worker
+   *
+   * @param {string} [workerPath='atrac1-worker.min.js'] - Path to the worker script
+   */
+  constructor(workerPath = 'carta1-worker.min.js') {
+    this.worker = new Worker(workerPath)
+    this.nextJobId = 1
+    this.jobs = new Map()
+
+    // Handle worker responses
+    this.worker.onmessage = (e) => {
+      const { jobId, error, result } = e.data
+
+      if (!jobId) {
+        console.warn('Received message without jobId:', e.data)
+        return
+      }
+
+      if (this.jobs.has(jobId)) {
+        const { resolve, reject } = this.jobs.get(jobId)
+        this.jobs.delete(jobId)
+
+        if (error) {
+          reject(new Error(error))
+        } else if (result) {
+          resolve(result)
+        } else {
+          reject(new Error('Worker returned no result'))
+        }
+      } else {
+        console.warn('Received result for unknown job:', jobId)
+      }
+    }
+
+    // Handle worker errors
+    this.worker.onerror = (error) => {
+      console.error('Worker crashed:', error)
+      // Reject all pending jobs
+      for (const [, { reject }] of this.jobs) {
+        reject(new Error('Worker crashed: ' + error.message))
+      }
+      this.jobs.clear()
+    }
+  }
+
+  /**
+   * Encode PCM audio to ATRAC1 format
+   *
+   * @param {Float32Array|Array<Float32Array>} pcmData - PCM audio data
+   *   - Mono: Float32Array
+   *   - Stereo: [left, right] Float32Arrays
+   * @param {Object} [options={}] - Encoder options
+   * @param {number} [options.transientThresholdLow] - Low band transient threshold
+   * @param {number} [options.transientThresholdMid] - Mid band transient threshold
+   * @param {number} [options.transientThresholdHigh] - High band transient threshold
+   * @param {number} [options.normalizationDb] - Normalization level in dB
+   * @returns {Promise<Object>} Encoding result
+   * @returns {Blob} returns.aeaBlob - ATRAC1 encoded audio blob
+   * @returns {Object} returns.shortBlockData - Short block frame indices
+   */
+  async encode(pcmData, options = {}) {
+    const jobId = this.nextJobId++
+    return new Promise((resolve, reject) => {
+      this.jobs.set(jobId, { resolve, reject })
+      try {
+        // Ensure plain object for serialization
+        const plainOptions = { ...options }
+        this.worker.postMessage({
+          jobId,
+          type: 'encode',
+          pcmData,
+          options: plainOptions,
+        })
+      } catch (error) {
+        this.jobs.delete(jobId)
+        reject(error)
+      }
+    })
+  }
+
+  /**
+   * Decode ATRAC1 audio to PCM WAV format
+   *
+   * @param {Object} aea - ATRAC1 audio data
+   * @param {Uint8Array} aea.header - AEA file header
+   * @param {Array} aea.aeaData - Encoded frame data
+   * @param {Object} [aea.info] - Optional metadata
+   * @returns {Promise<Object>} Decoding result
+   * @returns {Blob} returns.wavBlob - Decoded WAV audio blob
+   * @returns {Object} returns.info - Audio metadata (channels, sample rate)
+   */
+  async decode(aea) {
+    const jobId = this.nextJobId++
+    return new Promise((resolve, reject) => {
+      this.jobs.set(jobId, { resolve, reject })
+      try {
+        this.worker.postMessage({ jobId, type: 'decode', aea })
+      } catch (error) {
+        this.jobs.delete(jobId)
+        reject(error)
+      }
+    })
+  }
+
+  /**
+   * Parse AEA file blob to extract metadata and frame data
+   *
+   * @param {Blob} blob - AEA file blob
+   * @returns {Promise<Object>} Parsed AEA data
+   * @returns {Uint8Array} returns.header - AEA file header
+   * @returns {Array} returns.aeaData - Encoded frame data
+   * @returns {Object} returns.info - Metadata (title, channels, frames)
+   */
+  async parseAeaBlob(blob) {
+    const jobId = this.nextJobId++
+    return new Promise((resolve, reject) => {
+      this.jobs.set(jobId, { resolve, reject })
+      try {
+        this.worker.postMessage({ jobId, type: 'parseAea', blob })
+      } catch (error) {
+        this.jobs.delete(jobId)
+        reject(error)
+      }
+    })
+  }
+
+  /**
+   * Get default encoder options metadata
+   *
+   * @returns {Promise<Object>} Default encoder options
+   */
+  async getEncoderOptions() {
+    const jobId = this.nextJobId++
+    return new Promise((resolve, reject) => {
+      this.jobs.set(jobId, { resolve, reject })
+      try {
+        this.worker.postMessage({ jobId, type: 'getEncoderOptions' })
+      } catch (error) {
+        this.jobs.delete(jobId)
+        reject(error)
+      }
+    })
+  }
+
+  /**
+   * Terminate the worker and clean up resources
+   *
+   * Call this when done using the codec to free memory
+   */
+  terminate() {
+    if (this.worker) {
+      this.worker.terminate()
+      this.worker = null
+    }
+    this.jobs.clear()
+  }
+}
+
+// Export for different module systems
+/* global define, window */
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = Carta1Worker
+} else if (typeof define === 'function' && define.amd) {
+  define([], function () {
+    return Carta1Worker
+  })
+} else if (typeof window !== 'undefined') {
+  // Global export for browser
+  window.Carta1Worker = Carta1Worker
+}

package/codec/browser/worker.js

@@ -0,0 +1,140 @@
+/**
+ * Carta1 Web Worker - Self-contained audio codec worker
+ *
+ * Provides asynchronous encoding and decoding of ATRAC1 audio format
+ * in a separate thread to prevent blocking the main UI thread.
+ *
+ * Usage:
+ *   Include this file as a web worker:
+ *   new Worker('carta1-worker.min.js')
+ */
+
+import { AeaFile } from '../io/serialization.js'
+import { EncoderOptions } from '../core/options.js'
+import { AudioProcessor } from '../io/processor.js'
+import { SAMPLE_RATE } from '../core/constants.js'
+
+/**
+ * Handle messages from the main thread
+ *
+ * Supported message types:
+ * - 'encode': Encode PCM to ATRAC1
+ * - 'decode': Decode ATRAC1 to PCM
+ * - 'parseAea': Parse AEA blob metadata
+ * - 'getEncoderOptions': Get default encoder options
+ */
+self.onmessage = async (e) => {
+  const { jobId, type, pcmData, aea, options, title, blob } = e.data
+
+  try {
+    let result
+
+    switch (type) {
+      case 'encode':
+        result = await encodeAtrac(pcmData, options, title)
+        break
+      case 'decode':
+        result = await decodeAtrac(aea)
+        break
+      case 'parseAea':
+        result = await AudioProcessor.parseAeaBlob(blob)
+        break
+      case 'getEncoderOptions':
+        result = getEncoderOptionsMetadata()
+        break
+      default:
+        throw new Error(`Unknown worker message type: ${type}`)
+    }
+
+    self.postMessage({ jobId, result })
+  } catch (error) {
+    console.error('Worker error:', error)
+    self.postMessage({ jobId, error: error.message })
+  }
+}
+
+/**
+ * Encode PCM audio data to ATRAC1 format
+ *
+ * @param {Array<Float32Array>} pcmData - PCM audio data [mono] or [left, right]
+ * @param {Object} options - Encoder options
+ * @returns {Promise<Object>} Encoded AEA blob
+ */
+async function encodeAtrac(pcmData, options, title) {
+  title = title ?? 'encoded by carta1'
+  try {
+    const audioFrames = AudioProcessor.frameBufferToFrames(pcmData)
+    const channelCount = pcmData.length
+
+    // Create encoder options from provided settings
+    const encoderOptions = new EncoderOptions(options)
+
+    const encodedFrames = AudioProcessor.encodeStream(audioFrames, {
+      channelCount,
+      encoderOptions,
+    })
+
+    const frameArray = await AudioProcessor.collectFrames(encodedFrames)
+
+    const aeaBlob = await AudioProcessor.createAeaBlob(frameArray, {
+      title,
+      channelCount,
+    })
+
+    // Return the blob
+    return { aeaBlob }
+  } catch (error) {
+    console.error('Worker encode error:', error)
+    throw error
+  }
+}
+
+/**
+ * Get default encoder options metadata
+ *
+ * @returns {Object} Default encoder options as plain object
+ */
+function getEncoderOptionsMetadata() {
+  const defaultOptions = new EncoderOptions()
+  return defaultOptions.toObject()
+}
+
+/**
+ * Decode ATRAC1 data to PCM WAV format
+ *
+ * @param {Object} aea - AEA data object
+ * @param {Uint8Array} aea.header - AEA file header
+ * @param {Array} aea.aeaData - Serialized frame data
+ * @param {Object} [aea.info] - Optional metadata
+ * @returns {Promise<Object>} WAV blob and decoding info
+ */
+async function decodeAtrac(aea) {
+  const { header, aeaData, info } = aea
+
+  // Use provided info, or fall back to header parsing, or defaults
+  let decodingInfo
+  if (info) {
+    decodingInfo = { sampleRate: SAMPLE_RATE, ...info }
+  } else if (header) {
+    const headerInfo = AeaFile.parseHeader(header)
+    decodingInfo = { sampleRate: SAMPLE_RATE, ...headerInfo }
+  } else {
+    decodingInfo = { channelCount: 2, sampleRate: SAMPLE_RATE }
+  }
+
+  const encodedFrameStream = AudioProcessor.deserializedFrameStream(aeaData)
+  const decodedFrames = AudioProcessor.decodeStream(encodedFrameStream, {
+    channelCount: decodingInfo.channelCount,
+  })
+
+  const pcmFrames = await AudioProcessor.collectFrames(decodedFrames)
+
+  // Create WAV blob directly
+  const wavBlob = AudioProcessor.createWavBlob(
+    pcmFrames,
+    decodingInfo.channelCount,
+    decodingInfo.sampleRate
+  )
+
+  return { wavBlob, info: decodingInfo }
+}