@hyperframes/inspector 0.8.206 → 0.8.208

package/dist/types/core/src/audioFade.d.ts

@@ -0,0 +1,23 @@
+/** Clip-edge fades: `data-fade-in` / `data-fade-out` in seconds, linear, multiplied on the resolved level. */
+export declare const HF_AUDIO_FADE_IN_ATTR = "data-fade-in";
+export declare const HF_AUDIO_FADE_OUT_ATTR = "data-fade-out";
+export declare const HF_AUDIO_FADE_IN_DATA_KEY: string;
+export declare const HF_AUDIO_FADE_OUT_DATA_KEY: string;
+export interface AudioFades {
+    /** Seconds from the clip start over which gain rises 0 → 1. */
+    fadeIn: number;
+    /** Seconds before the clip end over which gain falls 1 → 0. */
+    fadeOut: number;
+}
+export declare const NO_FADES: Readonly<AudioFades>;
+/** Attribute text as seconds: finite and positive, else 0 (no fade). */
+export declare function readFadeSeconds(raw: string | null | undefined): number;
+export declare function readElementFades(el: {
+    getAttribute(name: string): string | null;
+}): AudioFades;
+/** Scale fades that outrun the clip so they meet inside it. Infinite duration keeps them as authored. */
+export declare function clampFadesToDuration(fades: AudioFades, duration: number): AudioFades;
+/** Gain at `elapsed` into a clip of `duration`. 1 where no fade runs; the two multiply where they meet. */
+export declare function fadeGain(elapsed: number, duration: number, fades: AudioFades): number;
+/** Attribute text Studio writes: up to 2 decimals, no trailing zeros. */
+export declare function formatFadeSeconds(seconds: number): string;

package/dist/types/core/src/compiler/selectorIdTokens.d.ts

@@ -62,7 +62,7 @@ export declare function parseAttributeSelector(predicate: string): {
     name: string;
     rawName: string;
     namespace: AttributeNamespace;
-    operator: "=" | "~=" | "|=" | "^=" | "$=" | "*=";
+    operator: "=" | "*=" | "|=" | "^=" | "~=" | "$=";
     value: string;
     flag: string | undefined;
 } | null;

package/dist/types/core/src/runtime/mediaVolumeEnvelope.d.ts

@@ -0,0 +1,70 @@
+import type { RuntimeTimelineLike } from "./types.js";
+/**
+ * Shared volume-automation utilities used by both the renderer (offline PCM
+ * baking in audioVolumeEnvelope.ts) and the preview runtime (per-tick gain
+ * applied in syncRuntimeMedia).
+ *
+ * Keeping the two concerns in one place ensures preview and render derive the
+ * envelope from the same logic and the same probe samples.
+ */
+export interface VolumeKeyframe {
+    time: number;
+    volume: number;
+}
+/**
+ * Normalise raw keyframes to track-relative seconds: subtract `trackStart`,
+ * clamp to [0,1], sort, de-duplicate, and prepend a `baseVolume` anchor at
+ * t=0 when the first keyframe starts after the clip's begin.
+ *
+ * Returns an empty array when all keyframes are invalid — the caller should
+ * treat an empty envelope as "no automation, use static volume."
+ */
+export declare function normaliseEnvelope(keyframes: VolumeKeyframe[], trackStart: number, baseVolume: number): VolumeKeyframe[];
+/**
+ * Linearly interpolate the gain at time `t` (track-relative seconds) from a
+ * normalised envelope produced by `normaliseEnvelope`. Returns 1 when the
+ * envelope is empty.
+ */
+export declare function interpolateVolumeGain(envelope: VolumeKeyframe[], t: number): number;
+/**
+ * Probe a single media element's volume automation by seeking a GSAP timeline
+ * through the element's active window.
+ *
+ * Runs synchronously in the browser. The timeline is left at its current
+ * position after the probe (the next transport tick re-seeks it to `t`).
+ *
+ * Returns null when the element has no detectable automation (volume never
+ * changes from its initial `data-volume` value).
+ */
+export declare function probeElementVolumeKeyframes(el: HTMLAudioElement | HTMLVideoElement, seekTimeline: (t: number) => void, compositionDuration: number, sampleFps: number): VolumeKeyframe[] | null;
+export type RuntimeTimelineRef = Partial<Pick<RuntimeTimelineLike, "totalTime" | "seek" | "getChildren">>;
+export interface VolumeProbeOptions {
+    /**
+     * Render/probe pages must not sample the live visual timeline during runtime
+     * initialization. The producer discovers audio automation in its own
+     * isolated pass and bakes it before frame capture, so seeking here is both
+     * redundant and capable of materializing future zero-duration GSAP state.
+     *
+     * Preview callers omit this option and retain live automation discovery.
+     */
+    allowLiveTimelineSeek?: boolean;
+    movers?: () => VolumeMovers;
+}
+export interface VolumeMovers {
+    elements: Set<unknown>;
+    anySetter: boolean;
+    unknown: boolean;
+}
+export declare function volumeMoversOf(timeline: RuntimeTimelineRef): VolumeMovers;
+/**
+ * Probe a media element and, if volume automation is detected, store a
+ * NORMALISED envelope in `cache`. Safe to call with a null timeline — returns
+ * early.
+ *
+ * `probeElementVolumeKeyframes` stamps each keyframe with the timeline seek
+ * time it was sampled at. Everything downstream of this cache — like the
+ * renderer's PCM baker — indexes an envelope by track-relative seconds, so the
+ * rebase belongs here, at the one point that fills the cache, rather than at
+ * each read.
+ */
+export declare function probeAndCacheElementVolume(mediaEl: HTMLMediaElement, timeline: RuntimeTimelineRef | null | undefined, compositionDuration: number, cache: WeakMap<HTMLMediaElement, VolumeKeyframe[]>, options?: VolumeProbeOptions): void;

package/dist/types/core/src/runtime/types.d.ts

@@ -1,5 +1,8 @@
 import type { HfColorGradingTarget } from "../colorGrading.js";
 import type { RuntimeAnalyticsEvent } from "./analytics.js";
+import type { AudioFades } from "../audioFade.js";
+import type { RateSpec } from "../speedRamp.js";
+import type { VolumeKeyframe } from "./mediaVolumeEnvelope.js";
 export type RuntimeJson = string | number | boolean | null | RuntimeJson[] | {
     [key: string]: RuntimeJson;
 };
@@ -378,4 +381,22 @@ type RuntimeDataControlFields = {
 };
 type RuntimeBridgeControlAction = RuntimeBridgeControlActionBase | "set-runtime-data" | "clear-runtime-data";
 export type RuntimeBridgeControlMessage = RuntimeBridgeControlMessageBase & RuntimeDataControlFields;
+export type RuntimeMediaClip = {
+    el: HTMLVideoElement | HTMLAudioElement;
+    start: number;
+    /** The clip's own t=0 when a host's in-point cut its head; source time, lanes and fades run from it. */
+    origin?: number;
+    mediaStart: number;
+    duration: number;
+    end: number;
+    volume: number | null;
+    playbackRate: number;
+    /** The rate lane when the clip has one; otherwise `playbackRate`. */
+    rate?: RateSpec;
+    loop: boolean;
+    sourceDuration: number | null;
+    /** Probed from the GSAP timeline as the renderer does; when set they drive volume, not `data-volume`. */
+    volumeKeyframes?: VolumeKeyframe[];
+    fades?: AudioFades;
+};
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/inspector",
-  "version": "0.8.206",
+  "version": "0.8.208",
   "repository": {
     "type": "git",
     "url": "https://github.com/heygen-com/hyperframes",
@@ -43,8 +43,8 @@
     "htmlparser2": "^10.1.0",
     "postcss": "^8.5.8",
     "puppeteer-core": "^25.8.0",
-    "@hyperframes/core": "0.8.206",
-    "@hyperframes/parsers": "0.8.206"
+    "@hyperframes/core": "0.8.208",
+    "@hyperframes/parsers": "0.8.208"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",