@libraz/libsonare 1.7.2 → 1.8.1

package/src/worklet/protocol.ts

@@ -25,12 +25,26 @@ export interface SonareWorkletMeterSnapshot {
   rmsDbL: number;
   rmsDbR: number;
   correlation: number;
+  /**
+   * Left-channel inter-sample (true) peak in dB, from the ITU-R BS.1770-4
+   * polyphase reconstruction at 4x. A streaming measurement, and the render
+   * quantum makes that visible here: the centered reconstruction stencil needs a
+   * few future samples a realtime path does not have, so each block's last
+   * samples read marginally low (about 0.1 dB across 64..8192-sample blocks on a
+   * near-Nyquist tone, always under-reading). Use `meteringTruePeakDb` over the
+   * whole signal for an exact dBTP number.
+   */
   truePeakDbL: number;
+  /** Right-channel inter-sample (true) peak in dB. See {@link truePeakDbL}. */
   truePeakDbR: number;
   momentaryLufs: number;
   shortTermLufs: number;
   integratedLufs: number;
   gainReductionDb: number;
+  /** Maximum pre-trim input peak for the left channel, in dBFS. */
+  inputPeakDbL: number;
+  /** Maximum pre-trim input peak for the right channel, in dBFS. */
+  inputPeakDbR: number;
 }
 
 export interface SonareWorkletSpectrumSnapshot {
@@ -42,18 +56,21 @@ export interface SonareWorkletSpectrumSnapshot {
 export const SONARE_METER_RING_HEADER_INTS = 4;
 // Record layout: [frameLo, frameHi, targetId, peakDbL, peakDbR, rmsDbL, rmsDbR,
 // correlation, truePeakDbL, truePeakDbR, momentaryLufs, shortTermLufs,
-// integratedLufs, gainReductionDb].
+// integratedLufs, gainReductionDb, inputPeakDbL, inputPeakDbR].
 // The sample-frame index is monotonically increasing and quickly exceeds the
 // 2^24 exact-integer range of a single Float32 slot (~349 s at 48 kHz), so it is
 // stored split across two Float32 lanes (low 24 bits + high bits) for exact
 // reconstruction. See encodeFrameLo/encodeFrameHi/decodeFrame.
-export const SONARE_METER_RING_RECORD_FLOATS = 14;
+export const SONARE_METER_RING_RECORD_FLOATS = 16;
 export const SONARE_SPECTRUM_RING_HEADER_INTS = 5;
 // Scope ring header: [writeIndex, capacity, recordFloats, bands, maxPoints,
 // reserved]. Record layout: [frameLo, frameHi, targetId, bandCount, pointCount,
 // band0..band(bands-1), l0, r0, l1, r1, ... (maxPoints stereo pairs)].
 export const SONARE_SCOPE_RING_HEADER_INTS = 6;
 export const SONARE_SCOPE_RING_RECORD_PREFIX_FLOATS = 5;
+/** Scope band and goniometer point counts used when a caller supplies none. */
+export const SONARE_SCOPE_DEFAULT_BANDS = 48;
+export const SONARE_SCOPE_DEFAULT_MAX_POINTS = 32;
 
 /** Base for splitting a frame index into two exactly-representable Float32 lanes. */
 const SONARE_FRAME_LANE_BASE = 0x1000000; // 2^24
@@ -111,6 +128,10 @@ export enum SonareEngineCommandType {
   // Queueable lane monitor-mode transition. The worklet command vocabulary
   // deliberately leaves 18..25 unused; this is the stable ABI-v3 ordinal.
   SetTrackMonitorMode = 26,
+  // Queueable master-meter integrated-loudness reset. Numeric value 28 mirrors
+  // rt::CommandType::kResetMasterMeterIntegrated; 27 remains the appended MIDI
+  // UMP slot command in the native vocabulary.
+  ResetMasterLoudnessMeter = 28,
 }
 
 export enum SonareEngineTelemetryType {
@@ -140,6 +161,7 @@ export enum SonareEngineTelemetryError {
   MetronomeOverflow = 18,
   InvalidCommand = 19,
   MaxChannelsExceeded = 20,
+  ParameterBaseOverflow = 21,
 }
 
 export interface SonareMeterRingBuffer {
@@ -307,8 +329,24 @@ export interface SharedSpectrumRingWriter {
   recordFloats: number;
 }
 
+/**
+ * Shared finite dB floor (`sonare::constants::kFloorDb`). Every level-in-dB
+ * field on a worklet snapshot bottoms out here rather than at `-Infinity`.
+ */
+export const SONARE_FLOOR_DB = -120;
+
+/**
+ * Magnitude to dB with the shared finite floor.
+ *
+ * `-Infinity` is not a usable value for a meter reading: it propagates NaN
+ * through the usual `(db + 60) / 60 * height` bar geometry, serializes to
+ * `null` through `JSON.stringify`, and poisons `Math.min`/`Math.max`
+ * aggregation. The native meters have always floored at `kFloorDb`, so a
+ * producer emitting `-Infinity` also made the two worklets disagree about
+ * silence.
+ */
 export function toDb(value: number): number {
-  return value > 0 ? 20 * Math.log10(value) : Number.NEGATIVE_INFINITY;
+  return value > 0 ? Math.max(20 * Math.log10(value), SONARE_FLOOR_DB) : SONARE_FLOOR_DB;
 }
 
 export function isRecord(value: unknown): value is Record<string, unknown> {
@@ -360,6 +398,8 @@ export function readSonareMeterRingBuffer(
       shortTermLufs: ring.records[offset + 11],
       integratedLufs: ring.records[offset + 12],
       gainReductionDb: ring.records[offset + 13],
+      inputPeakDbL: ring.records[offset + 14],
+      inputPeakDbR: ring.records[offset + 15],
     });
   }
   return { nextReadIndex: writeIndex, meters };
@@ -429,8 +469,8 @@ export function sonareScopeRingRecordFloats(bands: number, maxPoints: number): n
 
 export function sonareScopeRingBufferByteLength(
   capacity: number,
-  bands = 48,
-  maxPoints = 32,
+  bands = SONARE_SCOPE_DEFAULT_BANDS,
+  maxPoints = SONARE_SCOPE_DEFAULT_MAX_POINTS,
 ): number {
   const clampedCapacity = Math.max(1, Math.floor(capacity));
   const clampedBands = Math.max(1, Math.floor(bands));
@@ -445,8 +485,8 @@ export function sonareScopeRingBufferByteLength(
 
 export function createSonareScopeRingBuffer(
   capacity = 64,
-  bands = 48,
-  maxPoints = 32,
+  bands = SONARE_SCOPE_DEFAULT_BANDS,
+  maxPoints = SONARE_SCOPE_DEFAULT_MAX_POINTS,
 ): SonareScopeRingBuffer {
   const clampedCapacity = Math.max(1, Math.floor(capacity));
   const clampedBands = Math.max(1, Math.floor(bands));
@@ -525,8 +565,14 @@ export function scopeRingFromSharedBuffer(
   const existingBands = Atomics.load(header, 3);
   const existingMaxPoints = Atomics.load(header, 4);
   const capacity = Math.max(1, Math.floor(existingCapacity || fallbackCapacity || 1));
-  const bands = Math.max(1, Math.floor(existingBands || fallbackBands || 48));
-  const maxPoints = Math.max(0, Math.floor(existingMaxPoints || (fallbackMaxPoints ?? 32)));
+  const bands = Math.max(
+    1,
+    Math.floor(existingBands || fallbackBands || SONARE_SCOPE_DEFAULT_BANDS),
+  );
+  const maxPoints = Math.max(
+    0,
+    Math.floor(existingMaxPoints || (fallbackMaxPoints ?? SONARE_SCOPE_DEFAULT_MAX_POINTS)),
+  );
   const recordFloats = sonareScopeRingRecordFloats(bands, maxPoints);
   const minBytes = sonareScopeRingBufferByteLength(capacity, bands, maxPoints);
   if (sharedBuffer.byteLength < minBytes) {
@@ -948,6 +994,27 @@ function recordOffset(index: number, capacity: number, recordBytes: number): num
   return (index % capacity) * recordBytes;
 }
 
+/**
+ * The domain of a uint32 record slot: no fraction, no sign, no overflow.
+ *
+ * `setUint32` folds anything outside it into a legal value, so a negative id
+ * becomes a large one and 2**32 becomes 0. An absent value is out of domain;
+ * a slot with a default resolves it before asking.
+ */
+export function isUint32Slot(value: number | undefined): boolean {
+  return (
+    typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= 0xffff_ffff
+  );
+}
+
+function toUint32Slot(value: number | undefined, fallback: number, name: string): number {
+  const resolved = value ?? fallback;
+  if (!isUint32Slot(resolved)) {
+    throw new RangeError(`${name} must be an integer within [0, 4294967295]`);
+  }
+  return resolved;
+}
+
 function toSafeInteger(value: number | bigint | undefined, fallback: number): number {
   const resolved = typeof value === 'bigint' ? Number(value) : value;
   if (resolved === undefined) {
@@ -976,8 +1043,10 @@ function writeEngineCommandRecord(
   offset: number,
   command: SonareEngineCommandRecord,
 ): void {
-  view.setUint32(offset, command.type, true);
-  view.setUint32(offset + 4, command.targetId ?? 0, true);
+  // Both slots are uint32 and the readers are unsigned, so the writer holds
+  // them to that domain; the command vocabulary itself is the node's check.
+  view.setUint32(offset, toUint32Slot(command.type, 0, 'type'), true);
+  view.setUint32(offset + 4, toUint32Slot(command.targetId, 0, 'targetId'), true);
   writeInt64Words(view, offset + 8, toSafeInteger(command.sampleTime, -1));
   // argFloat occupies a full 8-byte Float64 slot (replacing the old Float32 +
   // 4-byte pad) so PPQ scalars carried here keep full double precision over the
@@ -1052,6 +1121,8 @@ export function meterFromEngine(meter: EngineMeterTelemetry): SonareWorkletMeter
     shortTermLufs: meter.shortTermLufs,
     integratedLufs: meter.integratedLufs,
     gainReductionDb: meter.gainReductionDb,
+    inputPeakDbL: meter.inputPeakDbL,
+    inputPeakDbR: meter.inputPeakDbR,
   };
 }
 

package/src/worklet/voice-changer-processor.ts

@@ -1,6 +1,6 @@
 import { RealtimeVoiceChanger } from '../index';
-import type { WorkletInput, WorkletOutput } from './audio_types';
-import { isRealtimeVoiceChangerMessage } from './guards';
+import { copyPlanesToOutput, type WorkletInput, type WorkletOutput } from './audio_types';
+import { isRealtimeVoiceChangerMessage, requireChannelCount } from './guards';
 import type {
   SonareRealtimeVoiceChangerMessage,
   SonareRealtimeVoiceChangerWorkletProcessorOptions,
@@ -25,12 +25,14 @@ export class SonareRealtimeVoiceChangerWorkletProcessor {
   // Float32Arrays, so this avoids the per-sample interleave/deinterleave
   // passes that the older interleaved path needed.
   private planarChannels: Float32Array[];
+  // Reused so the mono fan-out never builds an array on the audio thread.
+  private readonly monoPlane: Float32Array[] = [new Float32Array(0)];
   private destroyed = false;
 
   constructor(options: SonareRealtimeVoiceChangerWorkletProcessorOptions = {}) {
     this.sampleRate = options.sampleRate ?? 48000;
     this.blockSize = options.blockSize ?? 128;
-    this.channelCount = Math.max(1, Math.floor(options.channelCount ?? 1));
+    this.channelCount = requireChannelCount(options.channelCount, 1);
     this.changer = new RealtimeVoiceChanger(options.preset ?? 'neutral-monitor');
     this.changer.prepare(this.sampleRate, this.blockSize, this.channelCount);
     // Acquire WASM-heap views once, sized to the worst case. These are alive
@@ -100,7 +102,14 @@ export class SonareRealtimeVoiceChangerWorkletProcessor {
         this.monoInput.fill(0, 0, frames);
       }
       this.changer.processPreparedMono(frames);
-      output[0].set(this.monoOutput.subarray(0, frames));
+      // One plane fans out to every output channel and anything it does not
+      // fill is zeroed. Writing only output[0] left a stereo host hard-panned
+      // left -- the default `channelCount` here is 1 while AudioWorkletNode's
+      // default `channelCountMode: 'max'` gives a 2-channel output, so that was
+      // the ordinary configuration -- and left the previous block's samples in
+      // the channels it skipped.
+      this.monoPlane[0] = this.monoOutput;
+      copyPlanesToOutput(output, this.monoPlane, frames);
       return true;
     }
 
@@ -122,13 +131,10 @@ export class SonareRealtimeVoiceChangerWorkletProcessor {
       }
     }
     this.changer.processPreparedPlanar(frames);
-    for (let ch = 0; ch < channels; ch++) {
-      const src = this.planarChannels[ch];
-      if (src) {
-        output[ch].set(src.subarray(0, frames));
-      }
-      // No `for frame` inner loop needed; output[ch] is a Float32Array.
-    }
+    // Same rule as the mono branch: an output channel past the last processed
+    // plane is silence rather than a duplicate of plane 0, and the tail past
+    // `frames` is zeroed.
+    copyPlanesToOutput(output, this.planarChannels, frames);
     return true;
   }
 

package/src/worklet.ts

@@ -26,6 +26,7 @@ export type {
   SonareEngineClipPageRequestMessage,
   SonareEngineSyncAutomationMessage,
   SonareEngineSyncBuiltinInstrumentMessage,
+  SonareEngineSyncBusStripEqBandMessage,
   SonareEngineSyncCaptureMessage,
   SonareEngineSyncClipsDeltaMessage,
   SonareEngineSyncClipsMessage,
@@ -48,6 +49,17 @@ export type {
   SonareEngineTransportFacade,
   SonareEngineTransportRequestMessage,
   SonareEngineTransportResponseMessage,
+  SonarePlaybackConfigMessage,
+  SonarePlaybackDestroyMessage,
+  SonarePlaybackDiagnosticsReplyMessage,
+  SonarePlaybackDiagnosticsRequestMessage,
+  SonarePlaybackErrorMessage,
+  SonarePlaybackMessage,
+  SonarePlaybackNodeOptions,
+  SonarePlaybackOrientationMessage,
+  SonarePlaybackResetMessage,
+  SonarePlaybackWorkletDiagnostics,
+  SonarePlaybackWorkletProcessorOptions,
   SonareRealtimeEngineNodeCapabilities,
   SonareRealtimeEngineNodeOptions,
   SonareRealtimeEngineWorkletProcessorOptions,
@@ -67,6 +79,11 @@ export {
   registerSonareWorkletProcessor,
   SonareWorkletProcessor,
 } from './worklet/mixer-processor';
+export {
+  createSonarePlaybackNode,
+  registerSonarePlaybackWorkletProcessor,
+  SonarePlaybackWorkletProcessor,
+} from './worklet/playback-processor';
 export {
   createSonareClipPageRequestRingBuffer,
   createSonareEngineCommandRingBuffer,