@nonstrict/recordkit 0.87.1 → 0.97.0

package/src/RecordingMetadata.ts

@@ -0,0 +1,125 @@
+// TypeScript mirrors of the Swift `Codable` types whose JSON is written to sidecar files inside a
+// RecordKit recording bundle. Consumers parse those JSON files and rely on these types to describe
+// their shape: property names are verbatim camelCase, Swift optionals become optional properties,
+// and Swift tagged-union enums encode as flat objects discriminated by a `type` field at the same
+// level as the payload.
+//
+// Keep this file in sync with the corresponding Swift sources:
+// - `RKWindowPresence.swift`
+// - `RKVideoDimensionChange.swift`
+// (The `RKBundleInfo` mirror, `BundleInfo`, lives in `Recorder.ts`.)
+
+import type { EventTime } from './InputEvents.js';
+
+/**
+ * Presence of a window at a point in time within a recording.
+ *
+ * Encoded as a flat object discriminated by `type`. Mirrors the Swift
+ * `RKWindowPresence` enum.
+ *
+ * @remarks
+ * The `present` member ({@link WindowInfo}) carries the window's position,
+ * size and identifying metadata at that moment; the `absent` member
+ * ({@link WindowAbsence}) marks a time at which the tracked window was not
+ * present (e.g. closed, minimized, or moved to another Space).
+ *
+ * @group Recording
+ */
+export type WindowPresence = WindowInfo | WindowAbsence;
+
+/**
+ * Information about a window that is present at a point in time within a recording.
+ *
+ * Mirrors the Swift `RKWindowInfo` struct (the `present` case of
+ * `RKWindowPresence`).
+ *
+ * @group Recording
+ */
+export interface WindowInfo {
+  type: 'present';
+
+  /** Time the event occurred in the recording. */
+  time: EventTime;
+
+  /** ID of the window. */
+  windowID: number;
+
+  /** Title of the window. */
+  windowTitle?: string;
+
+  /**
+   * ID of the macOS Space where this window lives (can be used to detect space changes).
+   *
+   * @remarks Mirrors a Swift `UInt64`; for very large Space IDs this can exceed JavaScript's
+   * `Number.MAX_SAFE_INTEGER`. ({@link WindowInfo.windowID} and {@link WindowInfo.applicationID}
+   * are 32-bit and not affected.)
+   */
+  spaceID?: number;
+
+  /** ID of the application the window belongs to. */
+  applicationID?: number;
+
+  /** Title of the application the window belongs to. */
+  applicationName?: string;
+
+  /** X-axis position of the window relative to the top left of recorded area, ranging from 0 to 1. */
+  x: number;
+
+  /** Y-axis position of the window relative to the top left of recorded area, ranging from 0 to 1. */
+  y: number;
+
+  /** Width of the window relative to the top left of recorded area, ranging from 0 to 1. */
+  width: number;
+
+  /** Height of the window relative to the top left of recorded area, ranging from 0 to 1. */
+  height: number;
+}
+
+/**
+ * Marks the absence of a window at a point in time within a recording.
+ *
+ * Mirrors the Swift `RKWindowAbsence` struct (the `absent` case of
+ * `RKWindowPresence`).
+ *
+ * @group Recording
+ */
+export interface WindowAbsence {
+  type: 'absent';
+
+  /** Time the event occurred in the recording. */
+  time: EventTime;
+}
+
+/**
+ * An event representing a video dimension change during recording.
+ * This can be caused by device rotation or other content size changes.
+ *
+ * Mirrors the Swift `RKVideoDimensionChange` struct.
+ *
+ * @group Recording
+ */
+export interface VideoDimensionChange {
+  /** Time the dimension change occurred in the recording. */
+  time: EventTime;
+
+  /** The original (pre-rotation) dimensions of the content, in pixels. */
+  dimensions: {
+    /** Content width in pixels. */
+    width: number;
+    /** Content height in pixels. */
+    height: number;
+  };
+
+  /**
+   * The rotation in degrees (0, 90, 180, or -90) that a player should apply to display
+   * this segment correctly. Positive values are clockwise, negative are counterclockwise.
+   */
+  rotation: number;
+
+  /**
+   * Whether the player should animate the transition to this rotation.
+   * `true` when device rotated during continuous recording.
+   * `false` at recording start or after pause/resume (instant change).
+   */
+  animated: boolean;
+}

package/src/WebAudioUtils.test.ts

@@ -0,0 +1,78 @@
+import { computeAudioLevel, createWebAudioBuffer } from './WebAudioUtils.js';
+import type { AudioStreamBuffer } from './Recorder.js';
+
+function buf(channelData: number[][], sampleRate = 48000): AudioStreamBuffer {
+  return {
+    sampleRate,
+    numberOfChannels: channelData.length,
+    numberOfFrames: channelData[0]?.length ?? 0,
+    channelData: channelData.map((c) => Float32Array.from(c)),
+  };
+}
+
+describe('computeAudioLevel', () => {
+  it('reports silence as zero amplitude and -Infinity dB', () => {
+    const level = computeAudioLevel(buf([[0, 0, 0, 0]]));
+    expect(level.rms).toBe(0);
+    expect(level.peak).toBe(0);
+    expect(level.rmsDb).toBe(-Infinity);
+    expect(level.peakDb).toBe(-Infinity);
+  });
+
+  it('computes RMS and peak, and their dBFS equivalents', () => {
+    // constant magnitude 0.5 -> rms == peak == 0.5 -> ~ -6.02 dBFS
+    const level = computeAudioLevel(buf([[0.5, -0.5, 0.5, -0.5]]));
+    expect(level.rms).toBeCloseTo(0.5, 5);
+    expect(level.peak).toBeCloseTo(0.5, 5);
+    expect(level.rmsDb).toBeCloseTo(20 * Math.log10(0.5), 4);
+    expect(level.peakDb).toBeCloseTo(20 * Math.log10(0.5), 4);
+  });
+
+  it('takes the peak as the max absolute sample across all channels', () => {
+    const level = computeAudioLevel(buf([[0.1, -0.9], [0.3, 0.2]]));
+    expect(level.peak).toBeCloseTo(0.9, 5);
+  });
+
+  it('treats a full-scale signal as 0 dBFS', () => {
+    const level = computeAudioLevel(buf([[1, -1, 1, -1]]));
+    expect(level.peakDb).toBeCloseTo(0, 5);
+  });
+
+  it('handles an empty buffer without dividing by zero', () => {
+    const level = computeAudioLevel(buf([[]]));
+    expect(level.rms).toBe(0);
+    expect(level.peakDb).toBe(-Infinity);
+  });
+});
+
+describe('createWebAudioBuffer', () => {
+  // Minimal AudioContext stub: createBuffer returns an object backed by Float32Arrays.
+  function fakeContext(): AudioContext {
+    const channels: Float32Array[] = [];
+    return {
+      createBuffer(numberOfChannels: number, numberOfFrames: number, _sampleRate: number) {
+        for (let i = 0; i < numberOfChannels; i++) channels[i] = new Float32Array(numberOfFrames);
+        return { getChannelData: (i: number) => channels[i] };
+      },
+    } as unknown as AudioContext;
+  }
+
+  it('copies channel data into a created AudioBuffer', () => {
+    const out = createWebAudioBuffer(buf([[0.1, 0.2, 0.3]]), fakeContext());
+    expect(out).not.toBeNull();
+    const data = out!.getChannelData(0);
+    expect(data.length).toBe(3);
+    expect(data[0]).toBeCloseTo(0.1, 5);
+    expect(data[1]).toBeCloseTo(0.2, 5);
+    expect(data[2]).toBeCloseTo(0.3, 5);
+  });
+
+  it('returns null for a malformed buffer instead of throwing (safe in stream callbacks)', () => {
+    const bad = { sampleRate: 48000, numberOfChannels: 2, numberOfFrames: 4, channelData: [Float32Array.from([0, 0, 0, 0])] } as AudioStreamBuffer;
+    expect(createWebAudioBuffer(bad, fakeContext())).toBeNull();
+  });
+
+  it('returns null when no usable AudioContext is provided', () => {
+    expect(createWebAudioBuffer(buf([[0.1]]), undefined as unknown as AudioContext)).toBeNull();
+  });
+});

package/src/WebAudioUtils.ts

@@ -105,4 +105,60 @@ export function createWebAudioBuffer(
     // Return null for any conversion failures - don't throw in streaming contexts
     return null;
   }
-}
+}
+
+/**
+ * An audio level measurement, as returned by {@link computeAudioLevel}.
+ *
+ * @group Recording
+ */
+export interface AudioLevel {
+  /** Root-mean-square (average) amplitude across all channels. Usually in `[0, 1]`, but can exceed `1` for hot or clipped signals. */
+  rms: number
+  /** Peak absolute amplitude across all channels. Usually in `[0, 1]`, but can exceed `1` for hot or clipped signals. */
+  peak: number
+  /** {@link AudioLevel.rms} in decibels relative to full scale (0 dBFS). `-Infinity` for silence; can exceed `0` for clipped signals. */
+  rmsDb: number
+  /** {@link AudioLevel.peak} in decibels relative to full scale (0 dBFS). `-Infinity` for silence; can exceed `0` for clipped signals. */
+  peakDb: number
+}
+
+/**
+ * Computes RMS and peak audio levels from an {@link AudioStreamBuffer}, for rendering a microphone (or
+ * system-audio) level meter.
+ *
+ * Electron has no dedicated microphone-preview component; the supported way to render a live level meter
+ * is to use a microphone/system-audio `stream` output and call this helper in your `streamCallback`.
+ *
+ * @example
+ * ```typescript
+ * import { computeAudioLevel } from '@nonstrict/recordkit';
+ *
+ * const streamCallback = (audioBuffer) => {
+ *   const { peakDb } = computeAudioLevel(audioBuffer);
+ *   meterElement.style.height = `${Math.max(0, 100 + peakDb)}%`; // -100 dB..0 dB -> 0%..100%
+ * };
+ * ```
+ *
+ * @group Recording
+ */
+export function computeAudioLevel(audioStreamBuffer: AudioStreamBuffer): AudioLevel {
+  let sumSquares = 0
+  let peak = 0
+  let count = 0
+
+  for (const channel of audioStreamBuffer.channelData) {
+    for (let i = 0; i < channel.length; i++) {
+      const sample = channel[i]
+      sumSquares += sample * sample
+      const abs = Math.abs(sample)
+      if (abs > peak) peak = abs
+      count++
+    }
+  }
+
+  const rms = count > 0 ? Math.sqrt(sumSquares / count) : 0
+  const toDb = (value: number) => value > 0 ? 20 * Math.log10(value) : -Infinity
+
+  return { rms, peak, rmsDb: toDb(rms), peakDb: toDb(peak) }
+}

package/src/WindowLevels.test.ts

@@ -0,0 +1,34 @@
+import { WINDOW_LEVELS } from './WindowLevels.js';
+
+// Pins the named macOS window levels that mirror RKWindow.Level, including the documented
+// shared-value aliases and front-to-back ordering.
+describe('WINDOW_LEVELS', () => {
+  it('pins known macOS window level values', () => {
+    expect(WINDOW_LEVELS.baseWindow).toBe(-2147483648);
+    expect(WINDOW_LEVELS.normal).toBe(0);
+    expect(WINDOW_LEVELS.floating).toBe(3);
+    expect(WINDOW_LEVELS.mainMenu).toBe(24);
+    expect(WINDOW_LEVELS.screenSaver).toBe(1000);
+    expect(WINDOW_LEVELS.maximumWindow).toBe(2147483631);
+  });
+
+  it('keeps the documented shared-value aliases equal', () => {
+    expect(WINDOW_LEVELS.submenu).toBe(WINDOW_LEVELS.floating);
+    expect(WINDOW_LEVELS.tornOffMenu).toBe(WINDOW_LEVELS.floating);
+    expect(WINDOW_LEVELS.screenSaver).toBe(WINDOW_LEVELS.screenSaverWindow);
+  });
+
+  it('orders front-to-back by increasing value (Comparable in Swift)', () => {
+    expect(WINDOW_LEVELS.normal).toBeLessThan(WINDOW_LEVELS.floating);
+    expect(WINDOW_LEVELS.floating).toBeLessThan(WINDOW_LEVELS.mainMenu);
+    expect(WINDOW_LEVELS.mainMenu).toBeLessThan(WINDOW_LEVELS.cursorWindow);
+  });
+
+  it('every level is an integer within the signed 32-bit range', () => {
+    for (const v of Object.values(WINDOW_LEVELS)) {
+      expect(Number.isInteger(v)).toBe(true);
+      expect(v).toBeGreaterThanOrEqual(-2147483648);
+      expect(v).toBeLessThanOrEqual(2147483647);
+    }
+  });
+});

package/src/WindowLevels.ts

@@ -0,0 +1,47 @@
+/**
+ * Named macOS window levels, mirroring RecordKit's `RKWindow.Level` Swift type.
+ *
+ * A {@link Window}'s `level` is a raw integer. macOS assigns windows to a small set of well-known
+ * levels; this map lets you compare a window's level against those named values, e.g.
+ *
+ * ```ts
+ * if (window.level === WINDOW_LEVELS.floating) { ... }
+ * if (window.level >= WINDOW_LEVELS.mainMenu) { ... } // at or above the menu bar
+ * ```
+ *
+ * Levels are `Comparable` in Swift: a higher number is drawn in front of a lower one. Some names
+ * share the same numeric value (e.g. `floating`, `submenu`, `tornOffMenu` are all `3`).
+ *
+ * @group Discovery
+ */
+export const WINDOW_LEVELS = {
+  baseWindow: -2147483648,
+  minimumWindow: -2147483643,
+  desktopWindow: -2147483623,
+  desktopIconWindow: -2147483603,
+  backstopMenu: -20,
+  normal: 0,
+  floating: 3,
+  submenu: 3,
+  tornOffMenu: 3,
+  modalPanel: 8,
+  utilityWindow: 19,
+  mainMenu: 24,
+  statusBar: 25,
+  popUpMenu: 101,
+  overlayWindow: 102,
+  helpWindow: 200,
+  draggingWindow: 500,
+  screenSaver: 1000,
+  screenSaverWindow: 1000,
+  assistiveTechHighWindow: 1500,
+  cursorWindow: 2147483630,
+  maximumWindow: 2147483631,
+} as const;
+
+/**
+ * The name of a well-known macOS window level. See {@link WINDOW_LEVELS}.
+ *
+ * @group Discovery
+ */
+export type WindowLevelName = keyof typeof WINDOW_LEVELS;

package/src/browser.ts

@@ -1,7 +1,17 @@
 // Browser-only exports - safe for use in browser environments
 // This entry point excludes Node.js-specific functionality like EventEmitter, crypto, etc.
 
-export { createWebAudioBuffer } from './WebAudioUtils.js';
+export { createWebAudioBuffer, computeAudioLevel } from './WebAudioUtils.js';
 
 // Type-only exports for browser use
-export type { AudioStreamBuffer } from './Recorder.js';
+export type { AudioStreamBuffer } from './Recorder.js';
+export type { AudioLevel } from './WebAudioUtils.js';
+
+// Sidecar JSON types (pure types, safe in the browser) — useful when parsing a recording bundle's
+// input-event / window-presence / dimension-change JSON files in a renderer process.
+export type * from './InputEvents.js';
+export type * from './RecordingMetadata.js';
+export type * from './Errors.js';
+export type * from './WindowLevels.js';
+export { RECORDKIT_ERROR_CODE_NUMBERS } from './Errors.js';
+export { WINDOW_LEVELS } from './WindowLevels.js';

package/src/index.ts

@@ -1,3 +1,11 @@
 export type * from './RecordKit.js';
 export type * from './Recorder.js';
+export type * from './InputEvents.js';
+export type * from './RecordingMetadata.js';
+export type * from './Errors.js';
+export type * from './WindowLevels.js';
+export type * from './WebAudioUtils.js';
 export { recordkit } from './RecordKit.js';
+export { RECORDKIT_ERROR_CODE_NUMBERS } from './Errors.js';
+export { WINDOW_LEVELS } from './WindowLevels.js';
+export { computeAudioLevel, createWebAudioBuffer } from './WebAudioUtils.js';

package/src/__snapshots__/NonstrictRPC.test.ts.snap

@@ -1,24 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`NonstrictRPC initialize sends init request w/o parameters 1`] = `
-{
-  "id": Any<String>,
-  "nsrpc": 1,
-  "procedure": "init",
-  "target": "TheTarget",
-  "type": "TheType",
-}
-`;
-
-exports[`NonstrictRPC initialize sends init request w/parameters 1`] = `
-{
-  "id": Any<String>,
-  "nsrpc": 1,
-  "params": {
-    "aParameter": "TheValue",
-  },
-  "procedure": "init",
-  "target": "TheTarget",
-  "type": "TheType",
-}
-`;