@make-pictures/core 0.0.0-stage → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 make.pictures (https://make.pictures)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+<p align="center">
+  <a href="https://make.pictures"><img src="https://make.pictures/brand/make-pictures-logo.svg" alt="make.pictures — Open-source 60 FPS Video-as-Code Studio" width="420" /></a>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@make-pictures/core"><img src="https://img.shields.io/npm/v/@make-pictures/core?style=for-the-badge&labelColor=0F172A&color=FF2A85&label=%40make-pictures%2Fcore" alt="@make-pictures/core on npm" /></a>
+  <img src="https://img.shields.io/badge/Deterministic_60_FPS_runtime-2563EB?style=for-the-badge&labelColor=0F172A" alt="Deterministic 60 FPS runtime" />
+  <a href="https://make.pictures"><img src="https://img.shields.io/badge/make.pictures-Studio-2563EB?style=for-the-badge&labelColor=0F172A" alt="make.pictures Studio" /></a>
+</p>
+
+# `@make-pictures/core`
+
+Deterministic **60 FPS Video-as-Code** core runtime for [`make.pictures`](https://make.pictures) — built on React, TypeScript, and Remotion.
+
+## Features
+
+- **Cinematography & Shot DSL (`@make-pictures/core/camera`):** `<DirectorCamera3D />` (`establishing-wide`, `medium`, `close-up`, `low-angle-hero`, `whip`, `glide`, `orbit`, optical `dollyZoomDeltaFov`, automatic `9:16` Golden Safe Box compensation) and `<DirectorCamera2D />`.
+- **Smart Audio Engine (`@make-pictures/core/audio`):** `<SmartMusicBed />` sidechain auto-ducking under narration, `useMusicBeatPulse`, `<SoundCue />` word-timestamp synchronization, and `VOICE_ACOUSTIC_FILTERS`.
+- **Production Manifest & Capsule Contracts (`@make-pictures/core`):** `defineProduction`, `productionAssetPath`, `SPRING_PRESETS` (`damping: 200`), `STUDIO_THEME`, `THEME`, and deterministic Mulberry32 `createSeededRandom`.
+
+## Install
+
+```bash
+npm install @make-pictures/core remotion @remotion/media-utils @remotion/google-fonts zod
+```
+
+## Usage
+
+```tsx
+import { spring, useCurrentFrame, useVideoConfig } from 'remotion';
+import { SPRING_PRESETS, createSeededRandom } from '@make-pictures/core';
+
+export const Hero: React.FC<{ title: string }> = ({ title }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  // frame 0 stays a clean board; damping: 200 means zero rubbery bounce
+  const enter = spring({ frame: frame - 2, fps, config: SPRING_PRESETS.snappy });
+  const seed = createSeededRandom('hero-v1')(); // deterministic, never Math.random()
+  return <h1 style={{ opacity: enter }} data-seed={seed}>{title}</h1>;
+};
+```
+
+## Links
+
+- Website: [make.pictures](https://make.pictures)
+- Source & docs: [github.com/make-pictures/make-pictures-studio](https://github.com/make-pictures/make-pictures-studio)
+- YouTube: [@makepicturestv](https://www.youtube.com/@makepicturestv) (EN) · [@makepicturespl](https://www.youtube.com/@makepicturespl) (PL)
+
+## License
+
+MIT © [make.pictures](https://make.pictures)

package/dist/audio/SmartMusicBed.d.ts

@@ -0,0 +1,61 @@
+import React from 'react';
+import type { SceneVoiceoverData } from '../types/scene';
+export interface DialogueDuckingSegment {
+    sceneId: string;
+    fromFrame: number;
+    durationInFrames: number;
+}
+export interface SmartMusicBedProps {
+    src: string;
+    dialogueSegments?: DialogueDuckingSegment[];
+    voiceoverManifest?: Record<string, SceneVoiceoverData>;
+    baseVolume?: number;
+    duckedVolume?: number;
+    lookaheadFrames?: number;
+    releaseFrames?: number;
+    fadeInFrames?: number;
+    fadeOutFrames?: number;
+    loop?: boolean;
+}
+export interface MusicBeatPulseOptions {
+    lowBinCount?: number;
+    smoothingFrames?: number;
+}
+/**
+ * Computes the continuous speech ducking weight in `0..1` (`0` = no speech / full music,
+ * `1` = active speech / ducked music) at `frame`, with smooth lookahead and release ramps.
+ */
+export declare function computeSpeechDuckingEnvelopeAtFrame(params: {
+    frame: number;
+    dialogueSegments?: DialogueDuckingSegment[];
+    voiceoverManifest?: Record<string, SceneVoiceoverData>;
+    lookaheadFrames?: number;
+    releaseFrames?: number;
+}): number;
+/**
+ * Computes the final music bed volume at `frame` combining intro/outro master fades
+ * and smooth sidechain speech ducking.
+ */
+export declare function computeMusicBedVolumeAtFrame(params: {
+    frame: number;
+    durationInFrames: number;
+    dialogueSegments?: DialogueDuckingSegment[];
+    voiceoverManifest?: Record<string, SceneVoiceoverData>;
+    baseVolume?: number;
+    duckedVolume?: number;
+    lookaheadFrames?: number;
+    releaseFrames?: number;
+    fadeInFrames?: number;
+    fadeOutFrames?: number;
+}): number;
+/**
+ * Broadcast-grade background music component with lookahead sidechain auto-ducking.
+ * Breathes up in intros, scene transitions, and pauses while ducking smoothly under dialogue.
+ */
+export declare const SmartMusicBed: React.FC<SmartMusicBedProps>;
+/**
+ * Extracts a smooth, normalized `0..1` low-frequency kick/bass transient pulse from `audioSrc`
+ * using `@remotion/media-utils` (`useAudioData` + `visualizeAudio`).
+ * Safely returns `0` when `audioSrc` is `null`, empty, or still loading.
+ */
+export declare function useMusicBeatPulse(audioSrc: string | null, options?: MusicBeatPulseOptions): number;

package/dist/audio/SoundCue.d.ts

@@ -0,0 +1,36 @@
+import React from 'react';
+import type { SceneVoiceoverData } from '../types/scene';
+export interface SoundCueCommonProps {
+    src: string;
+    volume?: number;
+    playbackRate?: number;
+    durationInFrames?: number;
+    offsetFrames?: number;
+}
+export interface SoundCueAtFrameProps extends SoundCueCommonProps {
+    atFrame: number;
+    sceneId?: undefined;
+    onWord?: undefined;
+    sceneStartFrame?: undefined;
+    fallbackFrame?: undefined;
+    voiceoverManifest?: undefined;
+}
+export interface SoundCueWordSyncProps extends SoundCueCommonProps {
+    atFrame?: undefined;
+    sceneId: string;
+    onWord: string;
+    sceneStartFrame?: number;
+    fallbackFrame?: number;
+    voiceoverManifest?: Record<string, SceneVoiceoverData>;
+}
+export type SoundCueProps = SoundCueAtFrameProps | SoundCueWordSyncProps;
+/**
+ * Resolves the exact composition frame (`>= 0`) at which a `<SoundCue />` fires.
+ */
+export declare function resolveSoundCueFrame(props: SoundCueProps): number;
+/**
+ * Declarative Foley & SFX component supporting either explicit `atFrame` timing
+ * or automatic word-level synchronization (`sceneId` + `onWord`).
+ * Uses `layout="none"` so it can be mounted safely inside both 2D HTML trees and 3D stages.
+ */
+export declare const SoundCue: React.FC<SoundCueProps>;

package/dist/audio/acousticPresets.d.ts

@@ -0,0 +1,15 @@
+import type { VoiceAcousticPreset } from '../types/scene';
+export type { VoiceAcousticPreset };
+/**
+ * Declarative ffmpeg `-af` filter chains for character and scene voice acoustics.
+ * Every preset preserves a 250ms silent tail (`apad=pad_dur=0.25`) so word endings
+ * never clip during playback or MP4 stitching.
+ */
+export declare const VOICE_ACOUSTIC_FILTERS: Record<VoiceAcousticPreset, string>;
+export declare const VOICE_ACOUSTIC_PRESET_NAMES: VoiceAcousticPreset[];
+export declare function isVoiceAcousticPreset(value: unknown): value is VoiceAcousticPreset;
+/**
+ * Resolves a declarative `VoiceAcousticPreset` name to an `ffmpeg -af` filter string.
+ * Defaults safely to `'clean'` (`apad=pad_dur=0.25`).
+ */
+export declare function getVoiceAcousticFilter(preset?: VoiceAcousticPreset): string;

package/dist/audio/index.cjs

@@ -0,0 +1,311 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/core/src/audio/index.ts
+var audio_exports = {};
+__export(audio_exports, {
+  SmartMusicBed: () => SmartMusicBed,
+  SoundCue: () => SoundCue,
+  VOICE_ACOUSTIC_FILTERS: () => VOICE_ACOUSTIC_FILTERS,
+  VOICE_ACOUSTIC_PRESET_NAMES: () => VOICE_ACOUSTIC_PRESET_NAMES,
+  computeMusicBedVolumeAtFrame: () => computeMusicBedVolumeAtFrame,
+  computeSpeechDuckingEnvelopeAtFrame: () => computeSpeechDuckingEnvelopeAtFrame,
+  getVoiceAcousticFilter: () => getVoiceAcousticFilter,
+  isVoiceAcousticPreset: () => isVoiceAcousticPreset,
+  resolveSoundCueFrame: () => resolveSoundCueFrame,
+  useMusicBeatPulse: () => useMusicBeatPulse
+});
+module.exports = __toCommonJS(audio_exports);
+
+// packages/core/src/audio/acousticPresets.ts
+var VOICE_ACOUSTIC_FILTERS = {
+  clean: "apad=pad_dur=0.25",
+  telephone: "highpass=f=340,lowpass=f=3200,acompressor=threshold=-16dB:ratio=3.5:attack=5:release=60,volume=1.18,apad=pad_dur=0.25",
+  "radio-walkie": "highpass=f=480,lowpass=f=2700,acrusher=bits=10:mix=0.28,acompressor=threshold=-18dB:ratio=4:attack=4:release=50,volume=1.22,apad=pad_dur=0.25",
+  cathedral: "highpass=f=140,aecho=0.82:0.78:48|96:0.32|0.18,lowpass=f=7800,volume=1.08,apad=pad_dur=0.25",
+  megaphone: "highpass=f=230,lowpass=f=3100,aecho=0.85:0.75:16:0.22,volume=1.15,apad=pad_dur=0.25",
+  "excitement-boost": "highpass=f=85,treble=g=2.0:f=4200,volume=1.32,alimiter=limit=0.96,apad=pad_dur=0.25"
+};
+var VOICE_ACOUSTIC_PRESET_NAMES = Object.keys(
+  VOICE_ACOUSTIC_FILTERS
+);
+function isVoiceAcousticPreset(value) {
+  return typeof value === "string" && Object.prototype.hasOwnProperty.call(VOICE_ACOUSTIC_FILTERS, value);
+}
+function getVoiceAcousticFilter(preset) {
+  if (!preset || !isVoiceAcousticPreset(preset)) {
+    return VOICE_ACOUSTIC_FILTERS.clean;
+  }
+  return VOICE_ACOUSTIC_FILTERS[preset];
+}
+
+// packages/core/src/audio/SmartMusicBed.tsx
+var import_react = require("react");
+var import_media_utils = require("@remotion/media-utils");
+var import_remotion = require("remotion");
+
+// packages/core/src/utils/timestamps.ts
+var REGISTERED_VOICEOVER_MANIFEST = {};
+function getSceneVoiceover(sceneId, manifest) {
+  if (manifest && manifest[sceneId]) {
+    return manifest[sceneId];
+  }
+  return REGISTERED_VOICEOVER_MANIFEST[sceneId];
+}
+function getWordTriggerFrame(sceneId, targetWord, fallbackFrame, manifest) {
+  const voiceover = getSceneVoiceover(sceneId, manifest);
+  if (!voiceover || !voiceover.words.length) {
+    return fallbackFrame;
+  }
+  const needle = targetWord.replace(/^[.,!?;:"'()[\]{}—–-]+|[.,!?;:"'()[\]{}—–-]+$/g, "").toLowerCase();
+  const exactMatch = voiceover.words.find((w) => w.normalizedWord === needle);
+  if (exactMatch) {
+    return exactMatch.startFrame;
+  }
+  const partialMatch = voiceover.words.find(
+    (w) => w.normalizedWord.includes(needle)
+  );
+  return partialMatch ? partialMatch.startFrame : fallbackFrame;
+}
+
+// packages/core/src/audio/SmartMusicBed.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var SILENT_WAV_DATA_URI = "data:audio/wav;base64,UklGRiYAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQIAAAAAAA==";
+function smoothstep01(value) {
+  const t = Math.max(0, Math.min(1, value));
+  return t * t * (3 - 2 * t);
+}
+function buildPhraseSpansForSegment(segment, manifest, mergeGapFrames) {
+  const vo = getSceneVoiceover(segment.sceneId, manifest);
+  const segStart = segment.fromFrame;
+  const segEnd = segment.fromFrame + Math.max(1, segment.durationInFrames);
+  if (!vo || !Array.isArray(vo.words) || vo.words.length === 0) {
+    return [{ start: segStart, end: segEnd }];
+  }
+  const spans = [];
+  for (const word of vo.words) {
+    const absStart = segStart + word.startFrame;
+    const absEnd = Math.min(segEnd + 18, segStart + Math.max(word.startFrame + 2, word.endFrame));
+    const prev = spans[spans.length - 1];
+    if (prev && absStart - prev.end <= mergeGapFrames) {
+      prev.end = Math.max(prev.end, absEnd);
+    } else {
+      spans.push({ start: absStart, end: absEnd });
+    }
+  }
+  return spans;
+}
+function computeSpeechDuckingEnvelopeAtFrame(params) {
+  const {
+    frame,
+    dialogueSegments = [],
+    voiceoverManifest,
+    lookaheadFrames = 12,
+    releaseFrames = 28
+  } = params;
+  if (dialogueSegments.length === 0) {
+    return 0;
+  }
+  const attack = Math.max(1, lookaheadFrames);
+  const release = Math.max(1, releaseFrames);
+  const mergeGap = attack + release + 10;
+  let maxWeight = 0;
+  for (const seg of dialogueSegments) {
+    const spans = buildPhraseSpansForSegment(seg, voiceoverManifest, mergeGap);
+    for (const span of spans) {
+      const rampIn = (0, import_remotion.interpolate)(
+        frame,
+        [span.start - attack, span.start + 4],
+        [0, 1],
+        { extrapolateLeft: "clamp", extrapolateRight: "clamp" }
+      );
+      const rampOut = (0, import_remotion.interpolate)(
+        frame,
+        [span.end - 2, span.end + release],
+        [1, 0],
+        { extrapolateLeft: "clamp", extrapolateRight: "clamp" }
+      );
+      const weight = smoothstep01(rampIn) * smoothstep01(rampOut);
+      if (weight > maxWeight) {
+        maxWeight = weight;
+      }
+    }
+  }
+  return maxWeight;
+}
+function computeMusicBedVolumeAtFrame(params) {
+  const {
+    frame,
+    durationInFrames,
+    dialogueSegments = [],
+    voiceoverManifest,
+    baseVolume = 0.26,
+    duckedVolume = 0.085,
+    lookaheadFrames = 12,
+    releaseFrames = 28,
+    fadeInFrames = 30,
+    fadeOutFrames = 45
+  } = params;
+  const duckWeight = computeSpeechDuckingEnvelopeAtFrame({
+    frame,
+    dialogueSegments,
+    voiceoverManifest,
+    lookaheadFrames,
+    releaseFrames
+  });
+  const duckedGain = baseVolume + (duckedVolume - baseVolume) * duckWeight;
+  const rawFadeIn = fadeInFrames > 0 ? (0, import_remotion.interpolate)(frame, [0, fadeInFrames], [0, 1], {
+    extrapolateLeft: "clamp",
+    extrapolateRight: "clamp"
+  }) : 1;
+  const fadeOutStart = Math.max(0, durationInFrames - Math.max(0, fadeOutFrames));
+  const rawFadeOut = fadeOutFrames > 0 ? (0, import_remotion.interpolate)(frame, [fadeOutStart, durationInFrames], [1, 0], {
+    extrapolateLeft: "clamp",
+    extrapolateRight: "clamp"
+  }) : 1;
+  const masterEnvelope = smoothstep01(rawFadeIn) * smoothstep01(rawFadeOut);
+  return Math.max(0, Number((duckedGain * masterEnvelope).toFixed(5)));
+}
+var SmartMusicBed = ({
+  src,
+  dialogueSegments = [],
+  voiceoverManifest,
+  baseVolume = 0.26,
+  duckedVolume = 0.085,
+  lookaheadFrames = 12,
+  releaseFrames = 28,
+  fadeInFrames = 30,
+  fadeOutFrames = 45,
+  loop = true
+}) => {
+  const { durationInFrames } = (0, import_remotion.useVideoConfig)();
+  const volumeAtFrame = (0, import_react.useCallback)(
+    (f) => computeMusicBedVolumeAtFrame({
+      frame: f,
+      durationInFrames,
+      dialogueSegments,
+      voiceoverManifest,
+      baseVolume,
+      duckedVolume,
+      lookaheadFrames,
+      releaseFrames,
+      fadeInFrames,
+      fadeOutFrames
+    }),
+    [
+      durationInFrames,
+      dialogueSegments,
+      voiceoverManifest,
+      baseVolume,
+      duckedVolume,
+      lookaheadFrames,
+      releaseFrames,
+      fadeInFrames,
+      fadeOutFrames
+    ]
+  );
+  if (!src) {
+    return null;
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_remotion.Sequence, { from: 0, durationInFrames, layout: "none", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    import_remotion.Audio,
+    {
+      src,
+      loop,
+      loopVolumeCurveBehavior: "extend",
+      volume: volumeAtFrame
+    }
+  ) });
+};
+function useMusicBeatPulse(audioSrc, options) {
+  const frame = (0, import_remotion.useCurrentFrame)();
+  const { fps } = (0, import_remotion.useVideoConfig)();
+  const hasSource = Boolean(audioSrc && audioSrc.trim().length > 0);
+  const audioData = (0, import_media_utils.useAudioData)(hasSource ? audioSrc : SILENT_WAV_DATA_URI);
+  if (!hasSource || !audioData) {
+    return 0;
+  }
+  const totalAudioFrames = Math.max(
+    1,
+    Math.floor(audioData.durationInSeconds * fps)
+  );
+  const binCount = Math.max(1, Math.min(16, options?.lowBinCount ?? 4));
+  const windowSize = Math.max(1, Math.min(9, options?.smoothingFrames ?? 3));
+  const halfWindow = Math.floor(windowSize / 2);
+  let energySum = 0;
+  let sampleCount = 0;
+  for (let offset = -halfWindow; offset <= halfWindow; offset++) {
+    const wrappedFrame = ((frame + offset) % totalAudioFrames + totalAudioFrames) % totalAudioFrames;
+    const spectrum = (0, import_media_utils.visualizeAudio)({
+      audioData,
+      frame: wrappedFrame,
+      fps,
+      numberOfSamples: 32,
+      smoothing: true
+    });
+    let frameBass = 0;
+    for (let b = 0; b < binCount; b++) {
+      frameBass += spectrum[b] ?? 0;
+    }
+    energySum += frameBass / binCount;
+    sampleCount += 1;
+  }
+  const avgBass = sampleCount > 0 ? energySum / sampleCount : 0;
+  return Math.max(0, Math.min(1, Math.pow(avgBass * 2.4, 1.15)));
+}
+
+// packages/core/src/audio/SoundCue.tsx
+var import_remotion2 = require("remotion");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function resolveSoundCueFrame(props) {
+  const offset = props.offsetFrames ?? 0;
+  if (typeof props.atFrame === "number") {
+    return Math.max(0, Math.round(props.atFrame + offset));
+  }
+  const sceneStart = props.sceneStartFrame ?? 0;
+  const fallback = props.fallbackFrame ?? 0;
+  const localWordFrame = getWordTriggerFrame(
+    props.sceneId,
+    props.onWord,
+    fallback,
+    props.voiceoverManifest
+  );
+  return Math.max(0, Math.round(sceneStart + localWordFrame + offset));
+}
+var SoundCue = (props) => {
+  const {
+    src,
+    volume = 0.4,
+    playbackRate = 1,
+    durationInFrames
+  } = props;
+  if (!src) {
+    return null;
+  }
+  const resolvedFrame = resolveSoundCueFrame(props);
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+    import_remotion2.Sequence,
+    {
+      from: resolvedFrame,
+      durationInFrames,
+      layout: "none",
+      children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_remotion2.Audio, { src, volume, playbackRate })
+    }
+  );
+};

package/dist/audio/index.d.ts

@@ -0,0 +1,3 @@
+export { VOICE_ACOUSTIC_FILTERS, VOICE_ACOUSTIC_PRESET_NAMES, getVoiceAcousticFilter, isVoiceAcousticPreset, type VoiceAcousticPreset, } from './acousticPresets';
+export { SmartMusicBed, computeMusicBedVolumeAtFrame, computeSpeechDuckingEnvelopeAtFrame, useMusicBeatPulse, type DialogueDuckingSegment, type MusicBeatPulseOptions, type SmartMusicBedProps, } from './SmartMusicBed';
+export { SoundCue, resolveSoundCueFrame, type SoundCueAtFrameProps, type SoundCueCommonProps, type SoundCueProps, type SoundCueWordSyncProps, } from './SoundCue';

package/dist/audio/index.mjs

@@ -0,0 +1,25 @@
+import {
+  SmartMusicBed,
+  SoundCue,
+  VOICE_ACOUSTIC_FILTERS,
+  VOICE_ACOUSTIC_PRESET_NAMES,
+  computeMusicBedVolumeAtFrame,
+  computeSpeechDuckingEnvelopeAtFrame,
+  getVoiceAcousticFilter,
+  isVoiceAcousticPreset,
+  resolveSoundCueFrame,
+  useMusicBeatPulse
+} from "../chunk-7H3OMRSU.mjs";
+import "../chunk-TKRCK7OW.mjs";
+export {
+  SmartMusicBed,
+  SoundCue,
+  VOICE_ACOUSTIC_FILTERS,
+  VOICE_ACOUSTIC_PRESET_NAMES,
+  computeMusicBedVolumeAtFrame,
+  computeSpeechDuckingEnvelopeAtFrame,
+  getVoiceAcousticFilter,
+  isVoiceAcousticPreset,
+  resolveSoundCueFrame,
+  useMusicBeatPulse
+};

package/dist/camera/DirectorCamera2D.d.ts

@@ -0,0 +1,61 @@
+import React from 'react';
+import { type CameraImpulse, type CameraKeyframe2D, type DirectorCameraTelemetry, type ShotSpec2D, type StageNode2D } from './shotTypes';
+export interface EvaluateDirectorCamera2DParams {
+    frame: number;
+    fps: number;
+    stageWidth: number;
+    stageHeight: number;
+    keyframes?: ReadonlyArray<CameraKeyframe2D>;
+    nodes?: Record<string, StageNode2D>;
+    shots?: ReadonlyArray<ShotSpec2D>;
+    safeBox9x16Compensation?: boolean;
+    handheldIntensity?: number;
+    impulses?: ReadonlyArray<CameraImpulse>;
+    seed?: number;
+}
+export interface ResolvedCameraState2D {
+    x: number;
+    y: number;
+    zoom: number;
+    rotateZ: number;
+    telemetry: DirectorCameraTelemetry;
+}
+/**
+ * Converts declarative `nodes + shots` into exact `CameraKeyframe2D[]`,
+ * automatically fitting single or multi-node bounding boxes into either `16:9`
+ * or the `9:16 Golden Safe Box` (`x ∈ [40, 910], y ∈ [220, 1380]`).
+ */
+export declare function resolveShotsToKeyframes2D(nodes: Record<string, StageNode2D>, shots: ReadonlyArray<ShotSpec2D>, stageWidth: number, stageHeight: number, safeBox9x16Compensation?: boolean): CameraKeyframe2D[];
+/**
+ * Pure deterministic 2D infinite-canvas camera solver (`f(frame, fps, ...)`).
+ */
+export declare function evaluateDirectorCamera2D(params: EvaluateDirectorCamera2DParams): ResolvedCameraState2D;
+export interface DirectorCamera2DProps {
+    /** Raw camera keyframes (compatible with `CameraRig`) */
+    keyframes?: CameraKeyframe2D[];
+    /** Named 2D `NodeBox` dictionary for declarative Shot-DSL auto-framing */
+    nodes?: Record<string, StageNode2D>;
+    /** Declarative Shot-DSL target sequence resolved against `nodes` */
+    shots?: ShotSpec2D[];
+    stageWidth?: number;
+    stageHeight?: number;
+    variant?: 'light' | 'dark';
+    /** Automatically centers bounded targets inside the `9:16 Golden Safe Box` when `stageHeight > stageWidth` */
+    safeBox9x16Compensation?: boolean;
+    /** Subtle low-frequency handheld float intensity (default `0.15`) */
+    handheldIntensity?: number;
+    /** Damped harmonic camera shake impulses */
+    impulses?: CameraImpulse[];
+    seed?: number;
+    /** Toggle technical blueprint backdrop & grid (default `true`) */
+    showGrid?: boolean;
+    /** Optional viewport-pinned HUD / VFX layer (`<CinematicLensOverlay />`, etc.) */
+    overlay?: React.ReactNode;
+    children: React.ReactNode;
+}
+/**
+ * Shot-DSL Infinite-Canvas 2D Camera Rig with zero-clipping viewport-pinned
+ * blueprint grid, `9:16 Golden Safe Box` auto-framing, deterministic shake,
+ * and live `DirectorCameraTelemetryContext`.
+ */
+export declare const DirectorCamera2D: React.FC<DirectorCamera2DProps>;

package/dist/camera/DirectorCamera3D.d.ts

@@ -0,0 +1,56 @@
+import React from 'react';
+import { type CameraImpulse, type DirectorCameraTelemetry, type ShotSpec3D, type StageAnchor3D } from './shotTypes';
+export interface ResolvedCameraPose3D {
+    position: [number, number, number];
+    lookAt: [number, number, number];
+    fov: number;
+    rollDeg: number;
+    telemetry: DirectorCameraTelemetry;
+}
+export interface EvaluateDirectorCamera3DParams {
+    frame: number;
+    fps: number;
+    width: number;
+    height: number;
+    durationInFrames?: number;
+    anchors: Record<string, StageAnchor3D>;
+    shots: ReadonlyArray<ShotSpec3D>;
+    handheldIntensity?: number;
+    impulses?: ReadonlyArray<CameraImpulse>;
+    safeBox9x16Compensation?: boolean;
+    fovOffset?: number;
+    distanceScale?: number;
+    seed?: number;
+}
+/**
+ * Reads live camera telemetry (`velocity`, `focusDistance`, `activeShotIndex`)
+ * from either an enclosing `<DirectorCamera2D>` / `<DirectorCameraTelemetryProvider>`
+ * OR a sibling `<DirectorCamera3D>` inside `<ThreeCanvas>` at the exact current `frame`.
+ */
+export declare function useDirectorCameraTelemetry(): DirectorCameraTelemetry;
+/**
+ * Pure deterministic 3D Shot DSL evaluator (`f(frame, fps, width, height, props)`).
+ */
+export declare function evaluateDirectorCamera3D(params: EvaluateDirectorCamera3DParams): ResolvedCameraPose3D;
+export interface DirectorCameraTelemetryProviderProps {
+    telemetry: DirectorCameraTelemetry;
+    children: React.ReactNode;
+}
+export declare const DirectorCameraTelemetryProvider: React.FC<DirectorCameraTelemetryProviderProps>;
+export interface DirectorCamera3DProps {
+    anchors: Record<string, StageAnchor3D>;
+    shots: ShotSpec3D[];
+    handheldIntensity?: number;
+    impulses?: CameraImpulse[];
+    safeBox9x16Compensation?: boolean;
+    fovOffset?: number;
+    distanceScale?: number;
+    seed?: number;
+    children?: React.ReactNode;
+}
+/**
+ * Declarative 3D Shot-DSL Camera Rig for `@remotion/three` (`<ThreeCanvas>`).
+ * Resolves named `StageAnchor3D` targets and cinematic shot presets, automatically
+ * re-framing vertical `9:16` Shorts compositions into the Golden Safe Box (`y ∈ [220, 1380]`).
+ */
+export declare const DirectorCamera3D: React.FC<DirectorCamera3DProps>;