@hyperframes/studio 0.7.106 → 0.7.108

package/src/components/editor/propertyPanelAudioFxGroup.tsx

@@ -0,0 +1,299 @@
+/**
+ * The audio FX panel's bridge to the element/attribute world.
+ *
+ * Chain, carve and automation are all serialised onto the element the way colour
+ * grading carries its config, so persistence is an ordinary attribute write with
+ * no new server route. Split out of PropertyPanelFlat, which is at its size
+ * budget, and self-contained enough to test on its own.
+ */
+
+import { useState } from "react";
+import {
+  HF_AUDIO_FX_ATTR,
+  HF_AUDIO_FX_DATA_KEY,
+  parseAudioFxChain,
+  serializeAudioFxChain,
+  type HfAudioFxChain,
+} from "@hyperframes/core/audio-fx";
+import {
+  classifyAudioName,
+  HF_AUDIO_CARVE_ATTR,
+  normalizeCarveSettings,
+  type HfCarveSettings,
+} from "@hyperframes/core/audio-carve";
+import {
+  fxAutomationTarget,
+  parseAutomationTarget,
+  presetAutomationTarget,
+  sampleAutomationLane,
+  type HfAutomation,
+} from "@hyperframes/core/audio-automation";
+import {
+  automatedTargetsOf,
+  automationAttrValue,
+  HF_AUDIO_AUTOMATION_ATTR,
+  HF_AUDIO_AUTOMATION_DATA_KEY,
+  readPanelAutomation,
+  resolveAutomationRange,
+  withoutLane,
+  withSeededLane,
+} from "./propertyPanelAutomation";
+import type { DomEditSelection } from "./domEditingTypes";
+import { useLivePlayheadTime } from "../../hooks/useLivePlayheadTime";
+import { FxSection } from "./propertyPanelFxSection.js";
+import { clipStart } from "./propertyPanelAudioFxGroupUtils.js";
+import { useFxChainObserved } from "./useFxChainObserved.js";
+import { useFxCarve } from "./useFxCarve.js";
+import { useFxLevelling } from "./useFxLevelling.js";
+
+/**
+ * Bridges the FX panel to the element/attribute world. Chain and carve are
+ * serialised onto the element the way colour grading carries its config, so
+ * persistence is an ordinary attribute write with no new server route.
+ */
+export function AudioFxGroup({
+  element,
+  onSetAttributeQuiet: onSetAttributeQuietRaw,
+  onSetAttributeLive,
+}: {
+  element: DomEditSelection;
+  /**
+   * Every write here is quiet: it persists to the source and skips the preview
+   * reload, because the runtime applies chain and automation edits to the
+   * running graph — a reload would only interrupt the audio to reach the same
+   * state, which is heard as the track chopping.
+   *
+   * It does re-read the selection afterwards, which this panel depends on: each
+   * edit is computed from the current attribute, so without the resync a second
+   * edit would work from a pre-edit value and appear to do nothing.
+   */
+  onSetAttributeQuiet: (attr: string, value: string | null) => void | Promise<void>;
+  /** Continuous, non-persisting write for a dial being dragged. */
+  onSetAttributeLive: (attr: string, value: string | null) => void | Promise<void>;
+}) {
+  const chain = ((): HfAudioFxChain => {
+    const raw = element.dataAttributes?.[HF_AUDIO_FX_DATA_KEY];
+    if (!raw) return { version: 1, nodes: [] };
+    try {
+      return parseAudioFxChain(raw);
+    } catch {
+      // Show an unreadable chain as empty rather than breaking the panel; the
+      // attribute is left untouched until the user changes something.
+      return { version: 1, nodes: [] };
+    }
+  })();
+
+  const automation = readPanelAutomation(
+    element.dataAttributes?.[HF_AUDIO_AUTOMATION_DATA_KEY],
+    chain,
+  );
+  const automatedTargets = automatedTargetsOf(automation);
+
+  /**
+   * What every automated knob is worth at the playhead, so the rack shows the
+   * value the audio is actually using rather than the one the attribute stores.
+   *
+   * An automated parameter has two values: the number sitting in the chain, which
+   * is only a seed once a lane exists, and the number the envelope is on right now.
+   * The second is the true one, and a rack that shows the first reads as broken
+   * during playback — the carve is visibly working and the readouts do not move.
+   *
+   * Sampled while paused as well, because the same argument applies to a scrub:
+   * the playhead is somewhere, and the envelope has a value there.
+   *
+   * Sampled off the clip too, which is not obvious. A lane holds its first value
+   * backwards and its last value forwards, so before the clip starts it already
+   * knows what it will open on — while the stored number is a seed the lane
+   * replaced and nothing will ever play. Showing that seed put a value on screen
+   * that the automation never uses, and made the fader jump the moment the clip
+   * came under the playhead.
+   */
+  const playhead = useLivePlayheadTime();
+  const localTime = playhead - clipStart(element.dataAttributes?.["start"]);
+  const liveAutomationValues = ((): Map<string, number> => {
+    const values = new Map<string, number>();
+    for (const lane of automation.lanes) {
+      const range = resolveAutomationRange(lane.target, chain);
+      if (!range) continue;
+      values.set(lane.target, sampleAutomationLane(lane, localTime, range.scale));
+    }
+    return values;
+  })();
+
+  const carve = ((): HfCarveSettings | null => {
+    const raw = element.dataAttributes?.["fx-carve"];
+    if (!raw) return null;
+    try {
+      return normalizeCarveSettings(JSON.parse(raw));
+    } catch {
+      return null;
+    }
+  })();
+
+  /**
+   * Every persisting write this panel makes, counted — see `useFxChainObserved`,
+   * which reports a chain that changed without one of these behind it as work
+   * something outside the studio did.
+   */
+  const onSetAttributeQuiet = useFxChainObserved(
+    element,
+    chain,
+    carve,
+    automation,
+    onSetAttributeQuietRaw,
+  );
+
+  // Written through the live path on purpose. It persists to the source just
+  // like the refreshing one, but skips the preview reload — and a reload
+  // restarts every playing track, which is heard as the audio chopping. The
+  // runtime follows the attribute and swaps the graph in place instead.
+  const writeAutomation = (next: HfAutomation): void => {
+    void onSetAttributeQuiet(HF_AUDIO_AUTOMATION_ATTR, automationAttrValue(next) || null);
+  };
+
+  /**
+   * Start automating one effect parameter.
+   *
+   * The lane is seeded with a single point at the value the control currently
+   * holds, so switching to an envelope never changes the sound — it only moves
+   * where the value comes from. The author then adds points in the timeline.
+   */
+  const automateParam = (nodeId: string, paramKey: string): void => {
+    const target = fxAutomationTarget(nodeId, paramKey);
+    const node = chain.nodes.find((n) => n.id === nodeId);
+    const range = resolveAutomationRange(target, chain);
+    if (!node || !range) return;
+    const raw = node.params?.[paramKey];
+    writeAutomation(
+      withSeededLane(automation, target, typeof raw === "number" ? raw : range.default),
+    );
+  };
+
+  /** Stop automating it, handing the value back to the panel control. */
+  const removeParamAutomation = (nodeId: string, paramKey: string): void => {
+    writeAutomation(withoutLane(automation, fxAutomationTarget(nodeId, paramKey)));
+  };
+
+  /**
+   * Automate a whole preset's amount — the wet/dry blend around its run.
+   *
+   * Seeded where the preset already sits, so switching to a lane never changes
+   * the sound; the author then draws the ramp in the timeline. Same contract as
+   * automating one parameter, one level up.
+   */
+  const automatePreset = (presetId: string, amount: number): void => {
+    writeAutomation(withSeededLane(automation, presetAutomationTarget(presetId), amount));
+  };
+
+  const removePresetAutomation = (presetId: string): void => {
+    writeAutomation(withoutLane(automation, presetAutomationTarget(presetId)));
+  };
+
+  /** Presets a lane already drives, so the panel shows a readout not a slider. */
+  const automatedPresets = new Set(
+    automation.lanes
+      .map((lane) => parseAutomationTarget(lane.target))
+      .filter((t): t is { kind: "preset"; presetId: string } => t?.kind === "preset")
+      .map((t) => t.presetId),
+  );
+
+  /**
+   * Drop every lane belonging to these nodes, and optionally a whole-preset one.
+   *
+   * Takes a LIST rather than one id, because each call recomputes from the same
+   * render-time `automation` snapshot and writes the whole attribute: calling it
+   * per node in a loop meant every write but the last was discarded, and only
+   * the final node's lanes were actually removed. The rest survived as orphans,
+   * and with ids minted lowest-free the next effect added inherited one —
+   * arriving "Automated" with an envelope nobody drew, baked into the render.
+   */
+  const removeNodesAutomation = (nodeIds: readonly string[], presetId?: string): void => {
+    const prefixes = nodeIds.map((id) => `fx.${id}.`);
+    const kept = automation.lanes.filter(
+      (lane) =>
+        !prefixes.some((p) => lane.target.startsWith(p)) &&
+        !(presetId !== undefined && lane.target === presetAutomationTarget(presetId)),
+    );
+    if (kept.length !== automation.lanes.length) {
+      writeAutomation({ version: 1, lanes: kept });
+    }
+  };
+
+  const removeNodeAutomation = (nodeId: string): void => removeNodesAutomation([nodeId]);
+
+  const [analysing, setAnalysing] = useState(false);
+
+  const { carvedAgainstBy, sourceOptions, setCarve } = useFxCarve(
+    element,
+    chain,
+    carve,
+    automation,
+    onSetAttributeQuiet,
+    writeAutomation,
+    setAnalysing,
+  );
+
+  const { runLeveller, auditionTransport, auditioningLevel, auditionLevel, removeLeveller } =
+    useFxLevelling(
+      element,
+      chain,
+      automation,
+      onSetAttributeQuiet,
+      onSetAttributeLive,
+      setAnalysing,
+    );
+
+  return (
+    <FxSection
+      // Locked while the carve is measuring. `analyse` captures the chain and
+      // the automation BEFORE its fetch and decode, then rewrites the whole
+      // attribute from that snapshot — so an effect added, or a knob committed,
+      // during those seconds was silently discarded when the analysis landed.
+      // Only the Analyse button was disabled, so every other control in the rack
+      // stayed live throughout. Refusing the edit is honest; merging it into a
+      // measurement that did not account for it would not be.
+      disabled={analysing}
+      chain={chain}
+      automatedTargets={automatedTargets}
+      liveAutomationValues={liveAutomationValues}
+      onAutomateParam={automateParam}
+      onRemoveParamAutomation={removeParamAutomation}
+      onRemoveNodeAutomation={removeNodeAutomation}
+      onRemoveNodesAutomation={removeNodesAutomation}
+      onChainChange={(next) =>
+        // Live for the same reason as automation above: adding, removing or
+        // bypassing an effect is applied to the running graph, so a reload would
+        // only interrupt the audio to reach the same state.
+        onSetAttributeQuiet(
+          HF_AUDIO_FX_ATTR,
+          next.nodes.length ? serializeAudioFxChain(next) : null,
+        )
+      }
+      onAuditionTransport={auditionTransport}
+      onChainPreview={(next) =>
+        // Live writes skip the preview refresh entirely, so dragging a knob no
+        // longer reloads the composition and restarts playback on every pixel.
+        // The gesture-end write above is the one that resyncs.
+        onSetAttributeLive(HF_AUDIO_FX_ATTR, next.nodes.length ? serializeAudioFxChain(next) : null)
+      }
+      carve={carve}
+      onCarveChange={(next) => void setCarve(next)}
+      onCarvePreview={(next) => onSetAttributeLive(HF_AUDIO_CARVE_ATTR, JSON.stringify(next))}
+      sourceOptions={sourceOptions}
+      // What this track sounds like, by the same reading that decides which
+      // OTHER tracks a carve may listen to. The shelf uses it to stop offering
+      // "My voice sounds amateur" on a music bed.
+      trackKind={classifyAudioName(element.id, element.element?.getAttribute("src"))}
+      onLevel={() => void runLeveller()}
+      onRemoveLevel={removeLeveller}
+      levelled={chain.nodes.some((n) => n.fromLeveller)}
+      onAutomatePreset={automatePreset}
+      onRemovePresetAutomation={removePresetAutomation}
+      automatedPresets={automatedPresets}
+      onAuditionLevel={(on) => void auditionLevel(on)}
+      auditioningLevel={auditioningLevel}
+      carvedAgainstBy={carvedAgainstBy}
+      analysing={analysing}
+    />
+  );
+}

package/src/components/editor/propertyPanelAudioFxGroupUtils.ts

@@ -0,0 +1,21 @@
+/**
+ * Small clip-timing helpers shared by the FX group and its carve/levelling
+ * hooks — split out of `propertyPanelAudioFxGroup.tsx` so each file that needs
+ * "where does this clip sit" does not have to redefine it.
+ */
+
+/** Where a clip starts on the timeline, in seconds. */
+export function clipStart(value: string | null | undefined): number {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** A clip's span, with an unwritten duration left unbounded rather than zero. */
+export function spanOf(
+  start: string | null | undefined,
+  duration: string | null | undefined,
+): { start: number; duration: number | null } {
+  const n =
+    duration === null || duration === undefined || duration === "" ? Number.NaN : Number(duration);
+  return { start: clipStart(start), duration: Number.isFinite(n) ? n : null };
+}

package/src/components/editor/propertyPanelAutomation.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import type { HfAutomation } from "@hyperframes/core/audio-automation";
+import { automationAttrValue, withLane, withoutLane } from "./propertyPanelAutomation.js";
+
+const carved = (): HfAutomation => ({
+  version: 1,
+  lanes: [
+    { target: "fx.n1.gain", points: [{ t: 0, v: -6 }] },
+    { target: "fx.n2.gain", points: [{ t: 0, v: -9 }] },
+    { target: "volume", points: [{ t: 0, v: 0.8 }] },
+  ],
+});
+
+/**
+ * A script hands back a whole `HfAutomation` that describes only its OWN lane.
+ * Writing that to the attribute would take everything else with it — the
+ * carve's per-band lanes and the track's volume lane — which is silent, total,
+ * and only noticed later when the mix has quietly lost its ducking.
+ */
+describe("withLane", () => {
+  it("keeps every lane it was not asked about", () => {
+    const next = withLane(carved(), { target: "fx.n9.gain", points: [{ t: 0, v: 3 }] });
+    expect(next.lanes.map((l) => l.target).sort()).toEqual([
+      "fx.n1.gain",
+      "fx.n2.gain",
+      "fx.n9.gain",
+      "volume",
+    ]);
+    expect(next.lanes.find((l) => l.target === "volume")?.points).toEqual([{ t: 0, v: 0.8 }]);
+  });
+
+  it("replaces a lane rather than adding a second one for the same target", () => {
+    // Re-running a script must not leave two lanes fighting over one parameter.
+    const once = withLane(carved(), { target: "fx.n9.gain", points: [{ t: 0, v: 3 }] });
+    const twice = withLane(once, { target: "fx.n9.gain", points: [{ t: 0, v: 5 }] });
+    expect(twice.lanes.filter((l) => l.target === "fx.n9.gain")).toHaveLength(1);
+    expect(twice.lanes.find((l) => l.target === "fx.n9.gain")?.points).toEqual([{ t: 0, v: 5 }]);
+    expect(twice.lanes).toHaveLength(4);
+  });
+
+  it("does not mutate what it was given", () => {
+    const before = carved();
+    withLane(before, { target: "fx.n9.gain", points: [{ t: 0, v: 3 }] });
+    expect(before.lanes).toHaveLength(3);
+  });
+});
+
+describe("withoutLane", () => {
+  it("takes one lane and leaves the rest", () => {
+    // A node removed without its lane leaves an orphan driving a parameter that
+    // is no longer in the graph.
+    const next = withoutLane(carved(), "fx.n1.gain");
+    expect(next.lanes.map((l) => l.target)).toEqual(["fx.n2.gain", "volume"]);
+  });
+
+  it("empties the attribute when the last lane goes", () => {
+    const one: HfAutomation = { version: 1, lanes: [{ target: "fx.n1.gain", points: [] }] };
+    expect(automationAttrValue(withoutLane(one, "fx.n1.gain"))).toBe("");
+  });
+});

package/src/components/editor/propertyPanelAutomation.ts

@@ -0,0 +1,97 @@
+/**
+ * Reading and editing an element's automation from the property panel.
+ *
+ * Shared by the audio FX group (per-effect parameters) and the media section
+ * (track volume), so both agree on what "automated" means and both write the
+ * attribute the same way.
+ */
+
+import type { HfAutomationLane } from "@hyperframes/core/audio-automation";
+import {
+  HF_AUDIO_AUTOMATION_ATTR,
+  HF_AUDIO_AUTOMATION_DATA_KEY,
+  parseAutomation,
+  resolveAutomation,
+  resolveAutomationRange,
+  serializeAutomation,
+  type HfAutomation,
+} from "@hyperframes/core/audio-automation";
+import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
+
+const EMPTY: HfAutomation = { version: 1, lanes: [] };
+
+/**
+ * The element's automation as the panel should treat it.
+ *
+ * Pass the chain to have it bound: a lane whose effect has been deleted is then
+ * dropped rather than reported as automating something. Pass `undefined` when
+ * the caller genuinely does not know the chain — the volume section does not
+ * parse it — and every lane is preserved instead.
+ *
+ * That distinction matters because callers write this value straight back to the
+ * attribute. Resolving against a chain that was merely unavailable would delete
+ * every FX lane the moment someone automated the volume.
+ *
+ * An unreadable attribute reads as no automation rather than breaking the panel;
+ * it is left untouched until the author changes something.
+ */
+export function readPanelAutomation(
+  raw: string | undefined,
+  chain: HfAudioFxChain | undefined,
+): HfAutomation {
+  if (!raw) return EMPTY;
+  try {
+    const parsed = parseAutomation(raw);
+    return chain ? resolveAutomation(parsed, chain) : parsed;
+  } catch {
+    return EMPTY;
+  }
+}
+
+/** Targets the element currently automates. */
+export function automatedTargetsOf(automation: HfAutomation): Set<string> {
+  return new Set(automation.lanes.map((lane) => lane.target));
+}
+
+/**
+ * Add a lane for `target`, seeded with a single point at `current`.
+ *
+ * One point is a constant, so switching a parameter to an envelope does not
+ * change the sound — it only moves where the value comes from. The author then
+ * shapes it in the timeline.
+ */
+export function withSeededLane(
+  automation: HfAutomation,
+  target: string,
+  current: number,
+): HfAutomation {
+  if (automation.lanes.some((lane) => lane.target === target)) return automation;
+  return { version: 1, lanes: [...automation.lanes, { target, points: [{ t: 0, v: current }] }] };
+}
+
+/** Drop one lane, handing its value back to the panel control. */
+export function withoutLane(automation: HfAutomation, target: string): HfAutomation {
+  return { version: 1, lanes: automation.lanes.filter((lane) => lane.target !== target) };
+}
+
+/**
+ * Replace one lane, leaving every other lane alone.
+ *
+ * A script that hands back a whole `HfAutomation` describes only its OWN lane.
+ * Writing that wholesale would take the carve's lanes and the volume lane with
+ * it, so what the script produces has to be merged in by target rather than
+ * swapped for what is already there.
+ */
+export function withLane(automation: HfAutomation, lane: HfAutomationLane): HfAutomation {
+  return {
+    version: 1,
+    lanes: [...automation.lanes.filter((l) => l.target !== lane.target), lane],
+  };
+}
+
+/** The attribute value for an automation set; empty when nothing is automated. */
+export function automationAttrValue(automation: HfAutomation): string {
+  return automation.lanes.length > 0 ? serializeAutomation(automation) : "";
+}
+
+export { HF_AUDIO_AUTOMATION_ATTR, HF_AUDIO_AUTOMATION_DATA_KEY, resolveAutomationRange };

package/src/components/editor/propertyPanelFlatMediaSection.tsx

@@ -12,6 +12,7 @@ import {
 } from "./propertyPanelHelpers";
 import { FlatSelectRow, FlatSlider } from "./propertyPanelFlatPrimitives";
 import { FlatToggle } from "./propertyPanelFlatToggle";
+import { AutomationToggle } from "./propertyPanelFxControls";
 
 // fallow-ignore-next-line complexity
 export function FlatMediaSection({
@@ -22,6 +23,9 @@ export function FlatMediaSection({
   onSetAttribute,
   onSetHtmlAttribute,
   onRemoveBackground,
+  volumeAutomated,
+  onAutomateVolume,
+  onRemoveVolumeAutomation,
 }: {
   projectDir: string | null;
   element: DomEditSelection;
@@ -29,6 +33,10 @@ export function FlatMediaSection({
   onSetStyle: (prop: string, value: string) => void | Promise<void>;
   onSetAttribute: (attr: string, value: string) => void | Promise<void>;
   onSetHtmlAttribute: (attr: string, value: string | null) => void | Promise<void>;
+  /** A volume lane in the timeline drives the level; the slider cannot. */
+  volumeAutomated?: boolean;
+  onAutomateVolume?: () => void;
+  onRemoveVolumeAutomation?: () => void;
   onRemoveBackground?: (
     inputPath: string,
     options: {
@@ -197,15 +205,35 @@ export function FlatMediaSection({
       )}
       {(isVideo || isAudio) && (
         <>
-          <FlatSlider
-            label="Volume"
-            value={volumePercent}
-            min={0}
-            max={100}
-            tier={volumePercent === 100 ? "default" : "explicitCustom"}
-            displayValue={`${volumePercent}%`}
-            onCommit={(next) => void onSetAttribute("volume", formatNumericValue(next / 100))}
-          />
+          {/* The slider is disabled while a lane owns the level: a value set
+              here would be overwritten by the envelope on the next tick. The
+              toggle beside it carries the tooltip. */}
+          <div
+            className="hf-volume-row flex items-center gap-1"
+            data-volume-automated={volumeAutomated ? "" : undefined}
+          >
+            <div className="min-w-0 flex-1">
+              <FlatSlider
+                label="Volume"
+                value={volumePercent}
+                min={0}
+                max={100}
+                tier={volumePercent === 100 ? "default" : "explicitCustom"}
+                displayValue={`${volumePercent}%`}
+                disabled={volumeAutomated}
+                onCommit={(next) => void onSetAttribute("volume", formatNumericValue(next / 100))}
+              />
+            </div>
+            <AutomationToggle
+              paramKey="volume"
+              label="Volume"
+              automated={Boolean(volumeAutomated)}
+              onAutomate={onAutomateVolume ? () => onAutomateVolume() : undefined}
+              onRemoveAutomation={
+                onRemoveVolumeAutomation ? () => onRemoveVolumeAutomation() : undefined
+              }
+            />
+          </div>
           <FlatSlider
             label="Rate"
             value={playbackRate * 100}

package/src/components/editor/propertyPanelFlatProps.ts

@@ -16,6 +16,7 @@ export type PropertyPanelFlatProps = Pick<
   | "onSetAttribute"
   | "onSetAttributes"
   | "onSetAttributeLive"
+  | "onSetAttributeQuiet"
   | "onApplyColorGradingScope"
   | "onSetHtmlAttribute"
   | "onRemoveBackground"