carta1 1.1.9 → 1.2.0

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'
 
 /**