@hraness/slopcamera 3.2.6 → 3.2.8

package/apps/desktop/html-overlay/audio-reactivity.ts

@@ -0,0 +1,127 @@
+import { z } from "zod";
+
+import type { AudioReactivityBands } from "../core/music-analysis";
+
+export const HTML_AUDIO_REACTIVITY_RESOURCE_NAME = "audio-reactivity";
+export const HTML_AUDIO_REACTIVITY_RESOURCE_URL_PATH = "slopcamera/audio-reactivity.json";
+export const HTML_AUDIO_REACTIVITY_MAX_BYTES = 4 * 1024 * 1024;
+
+export type HtmlOverlayAudioReactivity = Readonly<{
+  kind: "slopcamera.audio-reactivity";
+  schemaVersion: 1;
+  profile: "bands-v1";
+  source: Readonly<{ bytes: number; sha256: string }>;
+  pcm: Readonly<{ sampleCount: number; sha256: string }>;
+  durationUs: number;
+  rateHz: 60;
+  bands: AudioReactivityBands;
+}>;
+
+export type HtmlOverlayAudioSample = Readonly<{
+  bass: number; mid: number; treble: number; energy: number;
+}>;
+export type PreparedHtmlOverlayAudioReactivity = Readonly<{
+  durationUs: number;
+  sample: (timeUs: number) => HtmlOverlayAudioSample;
+}>;
+
+const LIMITS = Object.freeze({ maxSamples: 14_400_000, maxSourceBytes: 512 * 1024 * 1024,
+  sampleRateHz: 24_000, hopSize: 400, rateHz: 60, maxTimeUs: 3_600_000_000 });
+
+/** One implementation validates the SDK and browser resource, before frame sampling. */
+function createAudioReactivityRuntime(limits: typeof LIMITS) {
+  const object = (value: unknown, keys: readonly string[]): Record<string, unknown> => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      throw new TypeError("Audio reactivity requires a strict JSON object.");
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (Reflect.ownKeys(value).length !== keys.length
+      || keys.some(key => descriptors[key] === undefined || !("value" in descriptors[key]!))) {
+      throw new TypeError("Audio reactivity contains missing, unknown, or accessor fields.");
+    }
+    return value as Record<string, unknown>;
+  };
+  const integer = (value: unknown, minimum: number, maximum: number): number => {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum) {
+      throw new RangeError("Audio reactivity integer is outside its bound.");
+    }
+    return value;
+  };
+  const digest = (value: unknown): string => {
+    if (typeof value !== "string" || !/^[a-f0-9]{64}$/u.test(value)) {
+      throw new TypeError("Audio reactivity requires a SHA-256 digest.");
+    }
+    return value;
+  };
+  const parse = (value: unknown): HtmlOverlayAudioReactivity => {
+    const input = object(value, ["kind", "schemaVersion", "profile", "source", "pcm", "durationUs", "rateHz", "bands"]);
+    if (input.kind !== "slopcamera.audio-reactivity" || input.schemaVersion !== 1
+      || input.profile !== "bands-v1" || input.rateHz !== limits.rateHz) {
+      throw new TypeError("Unsupported audio reactivity profile or version.");
+    }
+    const source = object(input.source, ["bytes", "sha256"]);
+    const pcm = object(input.pcm, ["sampleCount", "sha256"]);
+    const sampleCount = integer(pcm.sampleCount, 1, limits.maxSamples);
+    const durationUs = Math.round(sampleCount * 1_000_000 / limits.sampleRateHz);
+    if (input.durationUs !== durationUs) throw new RangeError("Audio reactivity duration differs from its PCM sample count.");
+    const length = Math.ceil(sampleCount / limits.hopSize) + 1;
+    const bands = object(input.bands, ["bass", "mid", "treble", "energy"]);
+    const channel = (value: unknown): readonly number[] => {
+      const keys = value !== null && typeof value === "object" ? Reflect.ownKeys(value) : [];
+      if (!Array.isArray(value) || value.length !== length || keys.length !== length + 1
+        || keys.some(key => key !== "length" && (typeof key !== "string" || !/^(?:0|[1-9][0-9]*)$/u.test(key)))) {
+        throw new RangeError("Audio reactivity bands must be dense arrays covering the declared duration.");
+      }
+      const copy: number[] = [];
+      for (let index = 0; index < length; index++) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        const sample: unknown = descriptor !== undefined && "value" in descriptor ? descriptor.value : undefined;
+        if (typeof sample !== "number" || !Number.isFinite(sample) || sample < 0 || sample > 1) {
+          throw new RangeError("Audio reactivity band values must be finite numbers in [0, 1].");
+        }
+        copy.push(sample === 0 ? 0 : sample);
+      }
+      if (copy.at(-1) !== 0) throw new RangeError("Audio reactivity requires a zero endpoint at the exact duration.");
+      return Object.freeze(copy);
+    };
+    return Object.freeze({
+      kind: "slopcamera.audio-reactivity", schemaVersion: 1, profile: "bands-v1", rateHz: 60, durationUs,
+      source: Object.freeze({ bytes: integer(source.bytes, 1, limits.maxSourceBytes), sha256: digest(source.sha256) }),
+      pcm: Object.freeze({ sampleCount, sha256: digest(pcm.sha256) }),
+      bands: Object.freeze({ bass: channel(bands.bass), mid: channel(bands.mid), treble: channel(bands.treble), energy: channel(bands.energy) }),
+    });
+  };
+  const prepareAudioReactivity = (input: unknown): PreparedHtmlOverlayAudioReactivity => {
+    const data = parse(input);
+    const zero = Object.freeze({ bass: 0, mid: 0, treble: 0, energy: 0 });
+    return Object.freeze({ durationUs: data.durationUs, sample(timeUs: number): HtmlOverlayAudioSample {
+      integer(timeUs, -limits.maxTimeUs, limits.maxTimeUs);
+      if (timeUs < 0 || timeUs >= data.durationUs) return zero;
+      const index = Math.min(data.bands.bass.length - 2, Math.floor(timeUs * limits.rateHz / 1_000_000));
+      const startUs = index * 1_000_000 / limits.rateHz;
+      const endUs = Math.min(data.durationUs, (index + 1) * 1_000_000 / limits.rateHz);
+      const mix = Math.max(0, Math.min(1, (timeUs - startUs) / (endUs - startUs)));
+      const interpolate = (band: readonly number[]) => band[index]! * (1 - mix) + band[index + 1]! * mix;
+      return Object.freeze({ bass: interpolate(data.bands.bass), mid: interpolate(data.bands.mid),
+        treble: interpolate(data.bands.treble), energy: interpolate(data.bands.energy) });
+    } });
+  };
+  return { parse, prepareAudioReactivity };
+}
+
+const runtime = createAudioReactivityRuntime(LIMITS);
+export const HtmlOverlayAudioReactivitySchema = z.unknown().transform((input, context): HtmlOverlayAudioReactivity => {
+  try { return runtime.parse(input); } catch (error) {
+    context.addIssue({ code: "custom", message: error instanceof Error ? error.message : "Invalid audio reactivity." });
+    return z.NEVER;
+  }
+});
+
+/** Validate and copy once. Samples depend only on absolute source time, in integer microseconds. */
+export function prepareHtmlOverlayAudioReactivity(input: unknown): PreparedHtmlOverlayAudioReactivity {
+  return runtime.prepareAudioReactivity(input);
+}
+
+export function createHtmlOverlayAudioReactivityRuntimeSource(): string {
+  return `(() => { const runtime = (${createAudioReactivityRuntime.toString()})(${JSON.stringify(LIMITS)}); return { prepareAudioReactivity: runtime.prepareAudioReactivity }; })()`;
+}

package/apps/desktop/html-overlay/contracts.ts

@@ -304,6 +304,9 @@ export const HtmlOverlayAuthoringInputSchema = z.strictObject({
   seed: Uint32Schema,
   timing: HtmlOverlayTimingSchema,
 }).superRefine((input, context) => {
+  // Zod may run refinements after a numeric bound fails. Leave that issue in
+  // the parse result instead of throwing from the checked frame-count helper.
+  if (!HtmlOverlayTimingSchema.safeParse(input.timing).success) return;
   const frames = htmlOverlayFrameCount(input.timing);
   if (frames > HTML_OVERLAY_MAX_FRAMES) {
     context.addIssue({

package/apps/desktop/html-overlay/index.ts

@@ -32,6 +32,16 @@ export {
   type HtmlOverlayRuntimeFrame,
   type HtmlOverlayTiming,
 } from "./contracts";
+export { HtmlSceneInputSchema, type HtmlSceneInput } from "./scene";
+export {
+  HTML_AUDIO_REACTIVITY_RESOURCE_NAME,
+  HTML_AUDIO_REACTIVITY_RESOURCE_URL_PATH,
+  HtmlOverlayAudioReactivitySchema,
+  prepareHtmlOverlayAudioReactivity,
+  type HtmlOverlayAudioReactivity,
+  type HtmlOverlayAudioSample,
+  type PreparedHtmlOverlayAudioReactivity,
+} from "./audio-reactivity";
 export {
   HTML_OVERLAY_SCAFFOLD_CLOCK_INTEGRATIONS,
   HTML_OVERLAY_SCAFFOLD_KINDS,
@@ -96,3 +106,21 @@ export {
   type HtmlOverlayScaffoldInput,
   type ThreeReferenceScaffoldInput,
 } from "./scaffolds";
+export {
+  HtmlOverlayMusicTimingSchema,
+  htmlOverlayMusicPulse,
+  sampleHtmlOverlayMusicClock,
+  type HtmlOverlayMusicSample,
+  type HtmlOverlayMusicTiming,
+} from "./music-clock";
+export {
+  THREE_RIGGED_GLB_LIMITS,
+  THREE_RIGGED_GLB_PROFILE,
+  PreparedThreeRiggedGlb,
+  createThreeRiggedGlbModule,
+  prepareThreeRiggedGlb,
+  type ThreeRiggedGlbInspection,
+  type ThreeRiggedGlbPrepareOptions,
+  type ThreeRiggedGlbProvenance,
+  type ThreeRiggedGlbResource,
+} from "./rigged-glb";

package/apps/desktop/html-overlay/music-clock.ts

@@ -0,0 +1,126 @@
+import { z } from "zod";
+
+import { HTML_OVERLAY_MAX_DURATION_US } from "./contracts";
+
+const MUSIC_CLOCK_LIMITS = Object.freeze({
+  maxBeatsPerBar: 32,
+  maxBpm: 400,
+  maxTimeUs: HTML_OVERLAY_MAX_DURATION_US,
+  minBeatsPerBar: 1,
+  minBpm: 20,
+});
+
+/** Explicit constant tempo and the absolute project time of beat zero. */
+export const HtmlOverlayMusicTimingSchema = z.strictObject({
+  beatOffsetUs: z.number().int().safe()
+    .min(-MUSIC_CLOCK_LIMITS.maxTimeUs).max(MUSIC_CLOCK_LIMITS.maxTimeUs),
+  beatsPerBar: z.number().int().safe()
+    .min(MUSIC_CLOCK_LIMITS.minBeatsPerBar).max(MUSIC_CLOCK_LIMITS.maxBeatsPerBar),
+  bpm: z.number().finite().min(MUSIC_CLOCK_LIMITS.minBpm).max(MUSIC_CLOCK_LIMITS.maxBpm),
+});
+export type HtmlOverlayMusicTiming = Readonly<z.infer<typeof HtmlOverlayMusicTimingSchema>>;
+
+export type HtmlOverlayMusicSample = Readonly<{
+  /** Zero-based signed bar index; pre-roll bars have negative indices. */
+  barIndex: number;
+  /** Normalized position within the bar, in [0, 1). */
+  barPhase: number;
+  /** Zero-based signed beat index, rounded toward negative infinity. */
+  beatIndex: number;
+  /** Normalized position within the beat, in [0, 1). */
+  beatPhase: number;
+  /** Signed elapsed beats since the explicitly supplied beat-zero offset. */
+  beatPosition: number;
+}>;
+
+type MusicClockRuntime = Readonly<{
+  musicClock: (timeUs: number, timing: unknown) => HtmlOverlayMusicSample;
+  musicPulse: (beatPhase: number, widthBeats?: number) => number;
+}>;
+
+/** This closure is self-contained so the browser and SDK execute the same code. */
+function createMusicClockRuntime(limits: typeof MUSIC_CLOCK_LIMITS): MusicClockRuntime {
+  const checkTimeUs = (timeUs: unknown): timeUs is number => (
+    typeof timeUs === "number"
+    && Number.isSafeInteger(timeUs)
+    && Math.abs(timeUs) <= limits.maxTimeUs
+  );
+
+  const musicClock = (timeUs: number, timing: unknown): HtmlOverlayMusicSample => {
+    if (!checkTimeUs(timeUs)) {
+      throw new RangeError(`HTML overlay music timeUs must be an integer within ±${String(limits.maxTimeUs)} microseconds.`);
+    }
+    if (timing === null || typeof timing !== "object" || Array.isArray(timing)) {
+      throw new TypeError("HTML overlay music timing must be an object with bpm, beatOffsetUs, and beatsPerBar.");
+    }
+    for (const key in timing) {
+      if (key !== "bpm" && key !== "beatOffsetUs" && key !== "beatsPerBar") {
+        throw new TypeError(`Unknown HTML overlay music timing field ${key}.`);
+      }
+    }
+    const { bpm, beatOffsetUs, beatsPerBar } = timing as Record<string, unknown>;
+    if (typeof bpm !== "number" || !Number.isFinite(bpm)
+      || bpm < limits.minBpm || bpm > limits.maxBpm) {
+      throw new RangeError(`HTML overlay music bpm must be between ${String(limits.minBpm)} and ${String(limits.maxBpm)}.`);
+    }
+    if (!checkTimeUs(beatOffsetUs)) {
+      throw new RangeError(`HTML overlay music beatOffsetUs must be an integer within ±${String(limits.maxTimeUs)} microseconds.`);
+    }
+    if (typeof beatsPerBar !== "number" || !Number.isSafeInteger(beatsPerBar)
+      || beatsPerBar < limits.minBeatsPerBar || beatsPerBar > limits.maxBeatsPerBar) {
+      throw new RangeError(`HTML overlay music beatsPerBar must be an integer between ${String(limits.minBeatsPerBar)} and ${String(limits.maxBeatsPerBar)}.`);
+    }
+
+    // Keep the continuous clock unquantized; floor gives consistent pre-roll.
+    // Canonicalize negative zero without changing any nonzero beat position.
+    const beatPosition = ((timeUs - beatOffsetUs) * bpm) / 60_000_000 || 0;
+    const beatIndex = Math.floor(beatPosition);
+    const beatPhase = beatPosition - beatIndex;
+    const barIndex = Math.floor(beatIndex / beatsPerBar);
+    const barPhase = (beatIndex - barIndex * beatsPerBar + beatPhase) / beatsPerBar;
+    return Object.freeze({ barIndex, barPhase, beatIndex, beatPhase, beatPosition });
+  };
+
+  const musicPulse = (beatPhase: number, widthBeats = 0.5): number => {
+    if (!Number.isFinite(beatPhase) || beatPhase < 0 || beatPhase >= 1) {
+      throw new RangeError("HTML overlay music beatPhase must be in [0, 1).");
+    }
+    if (!Number.isFinite(widthBeats) || widthBeats <= 0 || widthBeats > 1) {
+      throw new RangeError("HTML overlay music pulse widthBeats must be in (0, 1].");
+    }
+    const distance = Math.min(beatPhase, 1 - beatPhase);
+    // Divide before doubling so even a positive subnormal width stays defined.
+    const position = Math.min(1, (distance / widthBeats) * 2);
+    return 1 - position * position * (3 - 2 * position);
+  };
+
+  return Object.freeze({ musicClock, musicPulse });
+}
+
+const musicRuntime = createMusicClockRuntime(MUSIC_CLOCK_LIMITS);
+
+/** Samples absolute integer project time. This does not detect tempo or downbeats. */
+export function sampleHtmlOverlayMusicClock(
+  timeUs: number,
+  timing: HtmlOverlayMusicTiming,
+): HtmlOverlayMusicSample {
+  // Validate the original value with the shared browser boundary as well as the
+  // public schema; neither path silently strips an undeclared timing field.
+  const sample = musicRuntime.musicClock(timeUs, timing);
+  HtmlOverlayMusicTimingSchema.parse(timing);
+  return sample;
+}
+
+/**
+ * A periodic [0, 1] smoothstep pulse centered on each beat. widthBeats is the
+ * complete nonzero width, with equal anticipation and decay. Both the beat seam
+ * and the support edges have zero slope. This is an envelope, not flash analysis.
+ */
+export function htmlOverlayMusicPulse(beatPhase: number, widthBeats = 0.5): number {
+  return musicRuntime.musicPulse(beatPhase, widthBeats);
+}
+
+/** Internal browser integration: a complete expression with musicClock/musicPulse. */
+export function createHtmlOverlayMusicClockRuntimeSource(): string {
+  return `(${createMusicClockRuntime.toString()})(${JSON.stringify(MUSIC_CLOCK_LIMITS)})`;
+}