audio 2.0.0-1 → 2.0.0

package/stats.js

@@ -0,0 +1,255 @@
+/**
+ * Stats engine — block-level stat computation + unified stat query.
+ * Self-registers on import — exposes statSession on audio, adds fn.stat.
+ */
+
+import audio, { parseTime, LOAD } from './core.js'
+import { buildPlan, streamPlan, ensurePlan } from './plan.js'
+
+// ── Stat descriptor registry ────────────────────────────────────
+
+let statDefs = {}
+
+/** Register/query stat: audio.stat(), audio.stat(name), audio.stat(name, descriptor|blockFn) */
+audio.stat = function(name, desc) {
+  if (!arguments.length) return statDefs
+  if (arguments.length === 1) return statDefs[name]
+  if (typeof desc === 'function') desc = { block: desc }
+  statDefs[name] = desc
+}
+
+/** Create a stat computation session. ch inferred from first .page() call. */
+function statSession(sr) {
+  let fns, acc, ch, last = 0, rem = null, remLen = 0
+
+  function init(c) {
+    ch = c
+    fns = Object.entries(audio.stat())
+      .filter(([_, d]) => d.block)
+      .map(([name, d]) => ({ name, fn: d.block, ctx: { sampleRate: sr } }))
+    acc = Object.create(null)
+    for (let { name } of fns) acc[name] = Array.from({ length: ch }, () => [])
+  }
+
+  function processBlock(block) {
+    for (let { name, fn, ctx } of fns) {
+      let v = fn(block, ctx)
+      if (typeof v === 'number') for (let c = 0; c < ch; c++) acc[name][c].push(v)
+      else for (let c = 0; c < ch; c++) acc[name][c].push(v[c])
+    }
+  }
+
+  return {
+    page(page) {
+      if (!acc) init(page.length)
+      let BS = audio.BLOCK_SIZE, off = 0, len = page[0].length
+
+      // Complete partial remainder from previous push
+      if (remLen > 0) {
+        let need = BS - remLen
+        if (len >= need) {
+          for (let c = 0; c < ch; c++) rem[c].set(page[c].subarray(0, need), remLen)
+          processBlock(rem)
+          off = need
+          remLen = 0
+        } else {
+          for (let c = 0; c < ch; c++) rem[c].set(page[c].subarray(0, len), remLen)
+          remLen += len
+          return this
+        }
+      }
+
+      // Process full blocks
+      while (off + BS <= len) {
+        processBlock(Array.from({ length: ch }, (_, c) => page[c].subarray(off, off + BS)))
+        off += BS
+      }
+
+      // Buffer remainder
+      if (off < len) {
+        if (!rem) rem = Array.from({ length: ch }, () => new Float32Array(BS))
+        for (let c = 0; c < ch; c++) rem[c].set(page[c].subarray(off))
+        remLen = len - off
+      }
+
+      return this
+    },
+    /** Flush any buffered partial block as a short final block. */
+    flush() {
+      if (remLen > 0) {
+        processBlock(Array.from({ length: ch }, (_, c) => rem[c].subarray(0, remLen)))
+        remLen = 0
+      }
+    },
+    delta() {
+      if (!acc) return
+      let firstKey = Object.keys(acc)[0]
+      if (!firstKey) return
+      let cur = acc[firstKey][0].length
+      if (cur <= last) return
+      let d = { fromBlock: last }
+      for (let name in acc) d[name] = acc[name].map(a => new Float32Array(a.slice(last)))
+      last = cur
+      return d
+    },
+    done() {
+      this.flush()
+      let out = { blockSize: audio.BLOCK_SIZE }
+      if (acc) for (let name in acc) out[name] = acc[name].map(a => new Float32Array(a))
+      return out
+    }
+  }
+}
+
+// ── Bin reduction ────────────────────────────────────────────────
+
+function binReduce(src, from, to, bins, reduce) {
+  if (bins <= 0 || to <= from) return new Float32Array(Math.max(0, bins))
+  from = Math.max(0, from); to = Math.min(to, src.length)
+  if (to <= from) return new Float32Array(bins)
+  let out = new Float32Array(bins), bpp = (to - from) / bins
+  for (let i = 0; i < bins; i++) {
+    let a = from + Math.floor(i * bpp), b = Math.min(from + Math.floor((i + 1) * bpp), to)
+    if (b <= a) b = a + 1
+    out[i] = reduce(src, a, b)
+  }
+  return out
+}
+
+
+/** Remap source stats by segment layout (plan-only edits, no sample pipeline).
+ *  Falls back to null if segments are too complex to remap cheaply. */
+function remapStats(srcStats, plan, sr) {
+  let bs = srcStats.blockSize, segs = plan.segs, totalLen = plan.totalLen
+  // Check feasibility: only self-ref (undefined) and silence (null), rate ±1
+  for (let s of segs) {
+    let rate = s[3] || 1, ref = s[4]
+    if (ref !== undefined && ref !== null) return null  // external ref
+    if (Math.abs(rate) !== 1) return null               // resampled
+    if (s[0] % bs !== 0 || s[2] % bs !== 0) return null // unaligned — force recompute
+  }
+  let outBlocks = Math.ceil(totalLen / bs)
+  let fields = Object.keys(srcStats).filter(k => k !== 'blockSize' && Array.isArray(srcStats[k]))
+  let ch = srcStats[fields[0]]?.length || 1
+  let out = { blockSize: bs }
+  for (let f of fields) out[f] = Array.from({ length: ch }, () => new Float32Array(outBlocks))
+
+  for (let s of segs) {
+    let srcOff = s[0], count = s[1], dstOff = s[2], rate = s[3] || 1, ref = s[4]
+    let dstBlockStart = Math.floor(dstOff / bs)
+    let dstBlockEnd = Math.ceil((dstOff + count) / bs)
+    if (ref === null) continue // silence — Float32Array already zeroed
+
+    let srcBlockStart = Math.floor(srcOff / bs)
+    let srcBlocks = srcStats[fields[0]][0].length
+    let rev = rate < 0
+    for (let i = dstBlockStart; i < dstBlockEnd && i < outBlocks; i++) {
+      let si = rev ? srcBlockStart + (dstBlockEnd - 1 - i) : srcBlockStart + (i - dstBlockStart)
+      if (si < 0 || si >= srcBlocks) continue
+      for (let f of fields) for (let c = 0; c < ch; c++) out[f][c][i] = srcStats[f][c][si]
+    }
+  }
+  return out
+}
+
+
+// ── Self-register ────────────────────────────────────────────────
+
+audio.statSession = statSession
+
+/** Resolve block range from opts. Recomputes stats if edits are dirty. */
+export async function queryRange(inst, opts) {
+  await inst[LOAD]()
+  let at = parseTime(opts?.at), dur = parseTime(opts?.duration)
+  let hasRange = at != null || dur != null
+
+  if (inst.edits?.length && inst._.statsV !== inst.version) {
+    if (!inst._.srcStats) inst._.srcStats = inst.stats
+
+    // Range query on dirty edits — compute stats for just the requested range
+    if (hasRange) {
+      let plan = buildPlan(inst)
+      await ensurePlan(inst, plan, at || 0, dur)
+      let s = statSession(inst.sampleRate)
+      for (let chunk of streamPlan(inst, plan, at || 0, dur)) s.page(chunk)
+      let stats = s.done()
+      let first = Object.values(stats).find(v => v?.[0]?.length)
+      let blocks = first?.[0]?.length || 0
+      return { stats, ch: inst.channels, sr: inst.sampleRate, from: 0, to: blocks }
+    }
+
+    // Plan-only edits (no sample pipeline) — remap source stats by segments
+    let plan = buildPlan(inst)
+    if (!plan.pipeline.length && inst._.srcStats?.blockSize) {
+      let remapped = remapStats(inst._.srcStats, plan, inst.sampleRate)
+      if (remapped) { inst.stats = remapped; inst._.statsV = inst.version }
+      else {
+        let s = statSession(inst.sampleRate); await ensurePlan(inst, plan); for (let chunk of streamPlan(inst, plan)) s.page(chunk); inst.stats = s.done()
+        inst._.statsV = inst.version
+      }
+    } else {
+      // Full recompute — has sample-level ops
+      let s = statSession(inst.sampleRate); await ensurePlan(inst, plan); for (let chunk of streamPlan(inst, plan)) s.page(chunk); inst.stats = s.done()
+      inst._.statsV = inst.version
+    }
+  }
+  let sr = inst.sampleRate, bs = inst.stats?.blockSize
+  if (!bs) return { stats: inst.stats, ch: inst.channels, sr, from: 0, to: 0 }
+  let first = Object.values(inst.stats).find(v => v?.[0]?.length)
+  let blocks = first?.[0]?.length || 0
+  let atN = at != null && at < 0 ? inst.duration + at : at
+  let from = atN != null ? Math.floor(atN * sr / bs) : 0
+  let to = dur != null ? Math.ceil(((atN || 0) + dur) * sr / bs) : blocks
+  from = Math.max(0, Math.min(from, blocks))
+  to = Math.max(from, Math.min(to, blocks))
+  return { stats: inst.stats, ch: inst.channels, sr, from, to }
+}
+
+audio.fn.stat = async function(name, opts) {
+  // Array of stat names — parallel query, positional result
+  if (Array.isArray(name)) return Promise.all(name.map(n => this.stat(n, opts)))
+
+  // Instance methods (spectrum, cepstrum, etc.)
+  if (typeof this[name] === 'function' && !audio.stat(name)) return this[name](opts)
+
+  let { stats, ch, sr, from, to } = await queryRange(this, opts)
+  let bins = opts?.bins
+
+  // Resolve channel selection once
+  let chSel = opts?.channel
+  let perCh = Array.isArray(chSel)
+  let chs = chSel != null ? (perCh ? chSel : [chSel]) : Array.from({ length: ch }, (_, i) => i)
+
+  let desc = audio.stat(name)
+
+  // Derived stats — custom query (skip if bins requested on block stat)
+  if (desc?.query && bins == null) return desc.query(stats, chs, from, to, sr)
+
+  // Raw block stats
+  let src = stats[name], reduce = desc?.reduce
+  if (!src) throw new Error(`Unknown stat: '${name}'`)
+  if (!reduce) throw new Error(`No reducer for stat: '${name}'`)
+
+  // Binned mode
+  if (bins != null) {
+    let n = bins ?? (to - from)
+    let reduce1 = (c) => binReduce(src[c], from, to, n, reduce)
+    if (perCh) return chs.map(reduce1)
+    if (chs.length === 1) return reduce1(chs[0])
+    let out = new Float32Array(n), bpp = (to - from) / n
+    for (let i = 0; i < n; i++) {
+      let a = from + Math.floor(i * bpp), b = Math.min(from + Math.floor((i + 1) * bpp), to)
+      if (b <= a) b = a + 1
+      let sum = 0
+      for (let c of chs) sum += reduce(src[c], a, b)
+      out[i] = sum / chs.length
+    }
+    return out
+  }
+
+  // Scalar mode
+  if (perCh) return chs.map(c => reduce(src[c], from, to))
+  if (chs.length === 1) return reduce(src[chs[0]], from, to)
+  let vals = chs.map(c => reduce(src[c], from, to))
+  return vals.reduce((a, b) => a + b, 0) / vals.length
+}

package/index.js

@@ -1,107 +0,0 @@
-// Default values.
-var DEFAULT_SAMPLE_RATE = 44100;
-var DEFAULT_BIT_DEPTH = 16;
-var DEFAULT_CHANNELS = 2;
-var DEFAULT_BYTE_ORDER = 'LE';
-
-var Audio = function Audio(options, _replaceSource) {
-  options = options || {};
-
-  // Sample rate: PCM sample rate in hertz
-  this.sampleRate = options.sampleRate || DEFAULT_SAMPLE_RATE;
-
-  // Bit depth: PCM bit-depth.
-  this.bitDepth = options.bitDepth || DEFAULT_BIT_DEPTH;
-
-  // Amount of channels: Mono, stereo, etc.
-  this.channels = options.channels || DEFAULT_CHANNELS;
-
-  // Byte order: Either "BE" or "LE".
-  this.byteOrder = options.byteOrder || DEFAULT_BYTE_ORDER;
-
-  // Byte depth: Bit depth in bytes.
-  this._byteDepth = options._byteDepth || Math.ceil(this.bitDepth / 8);
-
-  // Block size: Byte depth alignment with channels.
-  this._blockSize = options._blockSize || this.channels * this._byteDepth;
-
-  // Block rate: Sample rate alignment with blocks.
-  this._blockRate = options._blockRate || this._blockSize * this.sampleRate;
-
-  // Source: Buffer containing PCM data that is formatted to the options.
-  if (options.source || _replaceSource) {
-    this.source = _replaceSource || options.source;
-  } else {
-    var length = this._blockRate * options.duration || 0;
-    this.source = new Buffer(length).fill(0);
-  }
-
-  // Check that the source is aligned with the block size.
-  if (this.source.length % this._blockSize !== 0 && !options.noAssert) {
-    throw new RangeError('Source is not aligned to the block size.');
-  }
-
-  // Length: The amount of blocks.
-  this.length = options.length || this.source.length / this._blockSize;
-
-  // Signed: Whether or not the PCM data is signed.
-  if (typeof options.signed === 'undefined') {
-    // If bit depth is 8 be unsigned, otherwise be signed.
-    this.signed = this.bitDepth !== 8;
-  } else {
-    this.signed = options.signed;
-  }
-
-  // Alias helper functions
-  var order = (this._byteDepth * 8) === 8 ? '' : this.byteOrder;
-  var sign = this.signed ? '' : 'U';
-  var typeTag = sign + 'Int' + (this._byteDepth * 8) + order;
-  this._write = this.source['write' + typeTag].bind(this.source);
-  this._read = this.source['read' + typeTag].bind(this.source);
-};
-
-Audio.prototype = {
-  constructor: Audio,
-
-  // Read sample data.
-  read: function read(offset, channel) {
-    channel = channel || 1;
-
-    // Align inputs to source bytes.
-    offset *= this._blockSize;
-    channel--;
-    channel *= this._byteDepth;
-
-    // Read value from source.
-    return this._read(offset + channel);
-  },
-
-  // Write sample data.
-  write: function write(value, offset, channel) {
-    channel = channel || 1;
-
-    // Align inputs to source bytes.
-    offset *= this._blockSize;
-    channel--;
-    channel *= this._byteDepth;
-
-    // Write value to source.
-    return this._write(value, offset + channel);
-  },
-
-  // Slice or replicate the audio.
-  slice: function slice(start, end) {
-    start = start || 0;
-    end = typeof end === 'number' ? end : this.length;
-
-    // Align start and end to blocs.
-    start *= this._blockSize;
-    end *= this._blockSize;
-
-    // Replicate self, with a new sliced source.
-    var override = this.source.slice(start, end);
-    return new Audio(this, override);
-  }
-};
-
-module.exports = Audio;